From 229c85373eb0409ebf2d38f51bb62be5f39975b2 Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Thu, 26 Mar 2026 12:11:02 +0100 Subject: [PATCH 1/2] docs: add CONVENTIONS.md and rewrite CONTRIBUTING.md CONVENTIONS.md: Mandatory technical rules for all contributors (human and AI). Covers SKILL.md format, plugin.json schema, Python script standards, sub-skill rules, cross-platform sync, and what NOT to contribute. CONTRIBUTING.md: Rewritten to reference CONVENTIONS.md. Fixed outdated guidance that contradicted actual repo conventions (was recommending license/metadata in frontmatter, wrong line limits, missing anti-patterns/cross-refs requirements). Co-Authored-By: Claude Opus 4.6 (1M context) --- CONTRIBUTING.md | 509 +++++++++++++++--------------------------------- CONVENTIONS.md | 289 +++++++++++++++++++++++++++ 2 files changed, 451 insertions(+), 347 deletions(-) create mode 100644 CONVENTIONS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e118c32..4dfd889 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,421 +1,236 @@ -# Contributing to Claude Skills Library +# Contributing to Claude Code Skills -Thank you for your interest in contributing to the Claude Skills Library! This repository aims to democratize professional expertise through reusable, production-ready skill packages for Claude AI. +Thank you for your interest in contributing! This repository is the largest open-source Claude Code skills & agent plugins library (6,800+ stars, 205 production-ready skills). -## ⚠️ Important: Always Target `dev` - -**All PRs must target the `dev` branch.** PRs targeting `main` will be automatically closed. - -```bash -# Fork the repo, then: -git checkout -b feat/my-new-skill origin/dev -# ... make your changes ... -# Open PR → base: dev (NOT main) -``` - -The `main` branch is reserved for releases and is maintained by the project owner. - -## 🎯 Ways to Contribute - -### 1. Create New Skills - -Add domain expertise in your field: -- Marketing, sales, customer success -- Engineering specializations -- Business functions (finance, HR, operations) -- Industry-specific skills (FinTech, EdTech, etc.) - -### 2. Enhance Existing Skills - -Improve current skills with: -- Better frameworks and templates -- Additional Python automation tools -- Updated best practices -- More reference materials -- Real-world examples and case studies - -### 3. Improve Documentation - -Help others use skills effectively: -- Clearer how-to guides -- Additional usage examples -- Better README files -- Translations to other languages - -### 4. Fix Bugs - -Report or fix issues in: -- Python scripts -- Documentation errors -- Broken links -- Outdated information +**Before you start:** Read [CONVENTIONS.md](CONVENTIONS.md) — it contains the mandatory technical rules that every contribution must follow. PRs that violate conventions will be closed. --- -## 🚀 Getting Started +## Target Branch: `dev` -### Prerequisites - -- Python 3.7+ (for running/testing scripts) -- Git and GitHub account -- Claude AI or Claude Code account (for testing skills) -- Familiarity with the skill domain you're contributing to - -### Fork and Clone +**All PRs must target the `dev` branch.** PRs targeting `main` will be closed automatically. ```bash -# Fork the repository on GitHub first git clone https://github.com/YOUR_USERNAME/claude-skills.git cd claude-skills - -# Add upstream remote git remote add upstream https://github.com/alirezarezvani/claude-skills.git +git fetch upstream dev +git checkout -b feature/my-skill upstream/dev ``` -### Create a Branch +--- + +## What We Accept + +### New Skills + +Add domain expertise that doesn't already exist in the repo: +- Engineering tools and workflows +- Marketing, sales, customer success patterns +- Product management frameworks +- Regulatory and compliance (ISO, SOC, GDPR, FDA) +- Business functions (finance, HR, operations) + +**Before building:** Check existing skills to avoid overlap. Open an issue to discuss if unsure. + +### Improvements to Existing Skills + +- Better workflows and actionable patterns +- Additional Python automation scripts +- New reference material +- More code examples and cross-references +- Bug fixes in scripts or documentation + +### Bug Fixes + +- Python scripts that fail `--help` +- Broken cross-references between skills +- Incorrect information in reference docs + +--- + +## What We Do NOT Accept + +| Type | Reason | +|------|--------| +| Links to external repos/tools in README | No 3rd party promotion | +| Skills requiring paid API keys | Must work without external services | +| Scripts with pip dependencies | stdlib-only Python | +| PRs that change the skill count (205) | Curated number | +| PRs modifying `.codex/`, `.gemini/`, `marketplace.json` | Auto-generated files | +| Bloated diffs with fork merge history | Rebase on `dev` first | +| Generic advice without actionable frameworks | Must be executable by an AI agent | + +--- + +## Skill Creation Guide + +### 1. Create the directory ```bash -# Create feature branch -git checkout -b feature/my-new-skill - -# Or for improvements -git checkout -b improvement/enhance-content-creator +# Example: new engineering skill +mkdir -p engineering/my-new-skill/scripts +mkdir -p engineering/my-new-skill/references ``` ---- +### 2. Write SKILL.md -## 📝 Skill Creation Guidelines +**Frontmatter — only `name` and `description`:** -### Following Anthropic's Official Spec - -All skills must follow [Anthropic's Agent Skills Specification](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview). - -### Required Structure - -``` -your-skill-name/ -├── SKILL.md (required) -│ ├── YAML frontmatter (name, description, license, metadata) -│ └── Markdown content (instructions, examples, workflows) -├── scripts/ (optional but recommended) -│ ├── tool1.py -│ ├── tool2.py -│ └── tool3.py -├── references/ (optional but recommended) -│ ├── framework.md -│ ├── best-practices.md -│ └── examples.md -└── assets/ (optional) - └── templates/ -``` - -### SKILL.md Requirements - -**YAML Frontmatter (required):** ```yaml --- -name: your-skill-name -description: What it does and when to use it. Include specific triggers and keywords. -license: MIT -metadata: - version: 1.0.0 - author: Your Name - category: domain-category - updated: 2025-10-28 +name: "my-new-skill" +description: "Use when the user asks to [specific trigger]. Covers [key capabilities]." --- ``` -**Markdown Content (required):** -- Clear heading and overview -- Keywords section for discovery -- Quick start guide -- Core workflows -- Script documentation (if applicable) -- Reference guide (if applicable) -- Best practices -- Examples +> **Important:** Do NOT add `license`, `metadata`, `triggers`, `version`, `author`, or any other fields. See [CONVENTIONS.md](CONVENTIONS.md) for the full specification. -**Target Length:** 100-200 lines for SKILL.md -- Keep core instructions lean -- Move detailed content to references/ -- Follow progressive disclosure principle +**Content must be:** +- Under 500 lines (move detailed content to `references/`) +- Opinionated (recommend specific approaches) +- Actionable (agent can execute, not just advise) +- Include anti-patterns and cross-references sections -### Python Script Standards +### 3. Write Python scripts (optional but valuable) -**Quality Requirements:** -- Production-ready code (not placeholders) -- Standard library preferred (minimal dependencies) -- CLI-first design with --help support -- JSON output option for automation -- Clear docstrings and comments -- Error handling and validation - -**Example:** ```python #!/usr/bin/env python3 -""" -Tool Name - Brief description +"""Tool Name — brief description.""" -Usage: - python tool.py input.txt [--output json] -""" +import argparse +import json +import sys def main(): - # Implementation - pass + parser = argparse.ArgumentParser(description="Tool description") + parser.add_argument("input", help="Input file or value") + parser.add_argument("--json", action="store_true", help="Output as JSON") + parser.add_argument("--verbose", action="store_true", help="Verbose output") + args = parser.parse_args() + + # Your logic here + result = {"status": "ok"} + + if args.json: + print(json.dumps(result, indent=2)) + else: + print(f"Result: {result['status']}") if __name__ == "__main__": main() ``` -### Documentation Standards +**Script rules:** stdlib-only, argparse, `--help`, `--json`, proper exit codes (0/1/2). See [CONVENTIONS.md](CONVENTIONS.md) for full requirements. -- Clear, actionable guidance -- Real-world examples -- Specific metrics and benchmarks -- No generic advice -- Professional tone -- Proper formatting +### 4. Add reference docs (optional) ---- +Place detailed material in `references/`: +``` +my-new-skill/references/ +├── patterns.md # Detailed patterns and examples +├── best-practices.md # Best practices guide +└── decision-matrix.md # Comparison tables +``` -## 🔄 Contribution Process +Reference them from SKILL.md: +```markdown +> See [references/patterns.md](references/patterns.md) for detailed patterns. +``` -### Step 1: Discuss First (Recommended) - -For major contributions: -1. Open an issue describing your idea -2. Discuss approach with maintainers -3. Get feedback before investing time -4. Avoid duplicate efforts - -### Step 2: Develop Your Contribution - -Follow the guidelines above for: -- New skills -- Python tools -- Documentation -- Bug fixes - -### Step 3: Test Thoroughly - -**For New Skills:** -- [ ] YAML frontmatter valid (no syntax errors) -- [ ] Description triggers Claude correctly -- [ ] All Python scripts work with --help -- [ ] All reference links work -- [ ] Skill activates when expected -- [ ] Tested with Claude AI or Claude Code - -**For Python Tools:** -- [ ] Runs without errors -- [ ] Handles edge cases -- [ ] Provides helpful error messages -- [ ] JSON output works (if applicable) -- [ ] Dependencies documented - -### Step 4: Submit Pull Request +### 5. Validate before submitting ```bash -# Commit your changes -git add . -git commit -m "feat(domain): add new-skill with [capabilities]" +# Structure validation +python3 engineering/skill-tester/scripts/skill_validator.py -# Push to your fork -git push origin feature/my-new-skill +# Script testing +python3 engineering/skill-tester/scripts/script_tester.py --verbose -# Create pull request on GitHub +# Security audit +python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py --strict ``` -**PR Title Format:** -- `feat(domain): add new skill for [purpose]` -- `fix(skill-name): correct issue with [component]` -- `docs(domain): improve documentation for [topic]` -- `refactor(skill-name): optimize [component]` +--- -**PR Description Must Include:** -- What: What does this add/change/fix? -- Why: Why is this valuable? -- Testing: How was it tested? -- Documentation: What docs were updated? +## PR Checklist + +Before submitting your PR, verify: + +- [ ] **Targets `dev` branch** (not `main`) +- [ ] **SKILL.md frontmatter** has only `name` + `description` +- [ ] **SKILL.md under 500 lines** (detailed content in `references/`) +- [ ] **All scripts pass** `python3 script.py --help` +- [ ] **Scripts use stdlib only** (no pip dependencies) +- [ ] **Scripts support `--json` output** +- [ ] **Anti-patterns section** included in SKILL.md +- [ ] **Cross-references** to related skills included +- [ ] **No modifications** to `.codex/`, `.gemini/`, `marketplace.json`, or index files +- [ ] **No 3rd party links** added to README +- [ ] **Clean diff** — rebased on `dev`, no merge commit history +- [ ] **Security audit passes** with zero CRITICAL/HIGH findings --- -## ✅ Quality Standards +## Commit Messages -### Skill Quality Checklist +[Conventional Commits](https://www.conventionalcommits.org/) format: -All new skills must meet these standards: - -**Documentation:** -- [ ] Clear SKILL.md with all required sections -- [ ] Enhanced description with triggers and keywords -- [ ] Keywords section for discovery -- [ ] Quick start guide with 2-3 examples -- [ ] Professional metadata (license, version, author) -- [ ] Domain-specific README updated (if applicable) - -**Python Tools (if included):** -- [ ] Production-ready code (not placeholders) -- [ ] CLI with --help support -- [ ] Proper error handling -- [ ] Clear docstrings -- [ ] Dependencies minimal and documented - -**References (if included):** -- [ ] Actionable frameworks and templates -- [ ] Specific guidance (not generic advice) -- [ ] Real-world benchmarks and examples -- [ ] Properly linked from SKILL.md - -**Testing:** -- [ ] Skill activates correctly with Claude -- [ ] All scripts execute without errors -- [ ] All links work -- [ ] No broken references - -**ROI:** -- [ ] Demonstrates measurable value -- [ ] Time savings quantified -- [ ] Quality improvements specified -- [ ] Clear use cases documented - ---- - -## 🎨 Style Guide - -### Python Code - -**Follow PEP 8:** -- 4 spaces for indentation -- Max line length: 100 characters -- Clear variable names -- Docstrings for functions - -**Example:** -```python -def analyze_content(text: str, keywords: list) -> dict: - """ - Analyze text content for keyword density and readability. - - Args: - text: Content to analyze - keywords: List of keywords to check - - Returns: - dict: Analysis results with scores and recommendations - """ - pass +``` +feat(engineering): add browser-automation skill +fix(self-improving-agent): use absolute path for hooks +improve(tdd-guide): add per-language examples +docs: update CONTRIBUTING.md ``` -### Markdown Documentation +--- -- Use headers consistently (H1 for title, H2 for sections) -- Include code blocks with language specification -- Use tables for comparisons -- Add emojis sparingly for visual hierarchy -- Keep paragraphs concise +## PR Description Template -### Commit Messages +```markdown +## Summary +- What: [What does this add/change/fix?] +- Why: [Why is this valuable?] -Follow [Conventional Commits](https://www.conventionalcommits.org/): - -- `feat(domain): add new capability` -- `fix(skill): correct bug in script` -- `docs(readme): update installation guide` -- `refactor(skill): optimize SKILL.md length` -- `test(tool): add test coverage` +## Checklist +- [x] Targets dev branch +- [x] SKILL.md frontmatter: name + description only +- [x] Under 500 lines +- [x] Scripts pass --help +- [x] Security audit: 0 critical/high findings +``` --- -## 🏆 Recognition +## After Your PR is Merged -### Contributors +Maintainers will handle: +1. Running sync scripts (Codex, Gemini, integrations) +2. Generating docs pages +3. Updating mkdocs.yml navigation +4. Updating domain plugin.json counts +5. Updating marketplace.json +6. Merging dev → main for deployment -All contributors will be: -- Listed in CHANGELOG.md for their contributions -- Mentioned in release notes -- Credited in PR merge messages -- Acknowledged in the community - -### Significant Contributions - -Major contributions may result in: -- Co-author credit in commits -- Feature attribution in documentation -- Highlighted in README -- Social media recognition +You do NOT need to do any of these steps in your PR. --- -## 📋 Domain-Specific Guidelines +## Recognition -### Marketing Skills - -- Include real benchmarks (CAC, conversion rates, etc.) -- Platform-specific guidance (LinkedIn, Google, etc.) -- B2B or B2C focus clearly stated -- International market considerations - -### Engineering Skills - -- Include tech stack in metadata -- Provide architecture patterns -- Add code quality standards -- Performance benchmarks - -### Product Skills - -- Include frameworks (RICE, OKR, etc.) -- Real-world metrics and KPIs -- Template-heavy with examples -- Integration points with tools - -### Regulatory/Quality Skills - -- Cite specific standards (ISO, FDA, EU MDR) -- Compliance frameworks clear -- Industry-specific (HealthTech, MedTech) -- Regulatory jurisdiction specified +Contributors are credited via: +- `Co-Authored-By:` in commit messages +- PR merge messages and changelogs +- Attribution in SKILL.md when skills are improved from community submissions --- -## 🚫 What NOT to Contribute +## Questions? -**We will not accept:** -- Generic advice without actionable frameworks -- Placeholder scripts (must be production-ready) -- Skills without clear use cases -- Duplicate capabilities of existing skills -- Proprietary or confidential information -- Content that violates licenses -- Skills promoting unethical practices +- **General:** Open a [discussion](https://github.com/alirezarezvani/claude-skills/discussions) +- **Bugs:** Use the [issue tracker](https://github.com/alirezarezvani/claude-skills/issues) +- **Contact:** [alirezarezvani.com](https://alirezarezvani.com) --- -## 🤝 Code of Conduct - -By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). - -Expected behavior: -- Be respectful and inclusive -- Provide constructive feedback -- Focus on what's best for the community -- Show empathy and kindness - ---- - -## 📞 Questions? - -- **General Questions:** Open a [discussion](https://github.com/alirezarezvani/claude-skills/discussions) -- **Bug Reports:** Use [bug report template](https://github.com/alirezarezvani/claude-skills/issues/new?template=bug_report.md) -- **Feature Ideas:** Use [feature request template](https://github.com/alirezarezvani/claude-skills/issues/new?template=feature_request.md) -- **Contact:** [alirezarezvani.com](https://alirezarezvani.com) or [medium.com/@alirezarezvani](https://medium.com/@alirezarezvani) - ---- - -## 🙏 Thank You! - -Your contributions help make world-class expertise accessible to everyone through Claude AI. Every skill added, bug fixed, or documentation improved makes a difference. - -**Happy contributing!** 🚀 +**Full technical conventions:** [CONVENTIONS.md](CONVENTIONS.md) diff --git a/CONVENTIONS.md b/CONVENTIONS.md new file mode 100644 index 0000000..52fbddf --- /dev/null +++ b/CONVENTIONS.md @@ -0,0 +1,289 @@ +# Repository Conventions + +**Mandatory conventions for the claude-code-skills repository.** Every contributor — human or AI coding agent — must follow these rules. PRs that violate them will be closed. + +For contribution workflow and how to submit PRs, see [CONTRIBUTING.md](CONTRIBUTING.md). + +--- + +## 1. Skill Structure + +Every skill is a directory under one of the 9 domain folders: + +``` +// +├── SKILL.md # Required — main skill file +├── .claude-plugin/ +│ └── plugin.json # Optional — for standalone installs +├── scripts/ # Optional — Python CLI tools +│ └── *.py +├── references/ # Optional — detailed reference docs +│ └── *.md +└── assets/ # Optional — templates, examples +``` + +### Domains + +| Directory | Category | Current Count | +|-----------|----------|---------------| +| `engineering/` | POWERFUL-tier advanced engineering | 35 | +| `engineering-team/` | Core engineering roles | 30 | +| `marketing-skill/` | Marketing & growth | 43 | +| `c-level-advisor/` | Executive advisory | 28 | +| `product-team/` | Product management | 14 | +| `ra-qm-team/` | Regulatory & quality | 13 | +| `project-management/` | PM tools | 6 | +| `business-growth/` | Sales & business dev | 4 | +| `finance/` | Financial analysis | 2 | + +Place your skill in the domain that best fits. If unsure, open an issue to discuss. + +--- + +## 2. SKILL.md Format + +### Frontmatter (YAML) + +**Only two fields are allowed:** + +```yaml +--- +name: "skill-name" +description: "One-line description of when to use this skill. Be specific about trigger conditions." +--- +``` + +**Do NOT include:** `license`, `metadata`, `triggers`, `version`, `author`, `category`, `updated`, or any other fields. PRs with extra frontmatter fields will be rejected. + +### Content Requirements + +| Requirement | Rule | +|-------------|------| +| **Line limit** | Under 500 lines. Move detailed content to `references/` files. | +| **Opinionated** | Recommend specific approaches. Don't just list options. | +| **Actionable** | The agent must be able to execute, not just advise. | +| **Anti-patterns** | Include a section on what NOT to do. | +| **Cross-references** | Link to related skills in the repo. | +| **Code examples** | Include concrete examples where helpful. | + +### Required Sections + +At minimum, every SKILL.md should include: + +1. **Title** (H1) — skill name +2. **Overview** — what it does, when to use it +3. **Core content** — workflows, patterns, instructions +4. **Anti-Patterns** — common mistakes to avoid +5. **Cross-References** — related skills in this repo + +Reference detailed material from `references/` files: +```markdown +> See [references/detailed-guide.md](references/detailed-guide.md) for full patterns. +``` + +--- + +## 3. plugin.json Format + +If your skill includes a `.claude-plugin/plugin.json`, use this **exact schema**: + +```json +{ + "name": "skill-name", + "description": "One-line description matching SKILL.md", + "version": "2.1.2", + "author": { + "name": "Alireza Rezvani", + "url": "https://alirezarezvani.com" + }, + "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main//", + "repository": "https://github.com/alirezarezvani/claude-skills", + "license": "MIT", + "skills": "./" +} +``` + +**Rules:** +- `author` **must be an object**, never a string. String format causes install errors. +- `version` must match the current repo version (`2.1.2`). +- No extra fields (`commands`, `hooks`, `triggers`, `tags`, `category`). +- Not every skill needs a plugin.json — skills roll up into their domain's parent plugin automatically. + +--- + +## 4. Python Scripts + +All scripts in `scripts/` must follow these rules: + +| Rule | Requirement | +|------|-------------| +| **Standard library only** | No pip dependencies. Use `argparse`, `json`, `os`, `re`, `sys`, etc. | +| **CLI-first** | Must support `python3 script.py --help` | +| **JSON output** | Must support `--json` flag for machine-readable output | +| **Exit codes** | `0` = success, `1` = warnings, `2` = critical errors | +| **No LLM calls** | Scripts must be deterministic — no API calls to AI services | +| **No hardcoded secrets** | Use environment variables for credentials | +| **Main guard** | Include `if __name__ == "__main__":` | + +**Example skeleton:** +```python +#!/usr/bin/env python3 +"""Tool Name — brief description.""" + +import argparse +import json +import sys + +def main(): + parser = argparse.ArgumentParser(description="Tool description") + parser.add_argument("--json", action="store_true", help="Output as JSON") + args = parser.parse_args() + + result = {"status": "ok"} + + if args.json: + print(json.dumps(result, indent=2)) + else: + print("Result: ok") + +if __name__ == "__main__": + main() +``` + +--- + +## 5. Sub-Skills + +Some skills contain sub-skills in a nested `skills/` directory: + +``` +engineering-team/playwright-pro/ +├── SKILL.md ← Parent skill +└── skills/ + ├── generate/SKILL.md ← Sub-skill + ├── fix/SKILL.md ← Sub-skill + └── migrate/SKILL.md ← Sub-skill +``` + +**Sub-skill rules:** +- Sub-skills are documented within their parent's docs page, NOT as standalone pages. +- Sub-skills do NOT get their own Codex/Gemini symlinks. +- Sub-skills do NOT count toward the official skill total. +- Do not create new sub-skill structures unless extending an existing compound skill. + +--- + +## 6. What NOT to Contribute + +The following will be **immediately closed**: + +| Type | Why | +|------|-----| +| Links to external repos/tools in README | We don't link 3rd party projects | +| Skills that require paid API keys | Must work without external dependencies | +| Skills that call LLMs in scripts | Scripts must be deterministic | +| PRs that change the official skill count (205) | This number is curated | +| PRs targeting `main` instead of `dev` | All PRs must target `dev` | +| PRs with bloated diffs (merge history from forks) | Rebase on `dev` HEAD first | +| PRs that modify marketplace.json counts | We handle count updates | +| PRs that modify codex/gemini index files | These are auto-generated | + +--- + +## 7. Cross-Platform Sync + +Platform copies are handled by automated scripts. **Do not create or modify these manually:** + +| Platform | Directory | Script | +|----------|-----------|--------| +| Codex CLI | `.codex/skills/` | `python3 scripts/sync-codex-skills.py` | +| Gemini CLI | `.gemini/skills/` | `python3 scripts/sync-gemini-skills.py` | +| Cursor/Aider/etc. | `integrations/` (gitignored) | `scripts/convert.sh --tool all` | + +After your skill is merged, maintainers run these scripts to sync all platforms. + +--- + +## 8. Docs Site + +Docs pages are auto-generated by `python3 scripts/generate-docs.py`. After your skill is merged, maintainers will: + +1. Run the docs generator +2. Add your skill to `mkdocs.yml` nav (alphabetical within domain) +3. Deploy via GitHub Pages + +You do NOT need to create docs pages in your PR. + +--- + +## 9. Git Conventions + +### Branch Naming + +``` +feature/ → New skill +fix/ → Bug fix +improve/ → Enhancement +docs/ → Documentation +``` + +### Commit Messages + +[Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +feat(engineering): add browser-automation skill +fix(self-improving-agent): use absolute path for hooks +improve(tdd-guide): add per-language examples +docs: update CONTRIBUTING.md +chore: sync codex/gemini indexes +``` + +### PR Requirements + +- **Target branch:** `dev` (never `main`) +- **One concern per PR** — don't bundle unrelated changes +- **Clean diff** — rebase on `dev` HEAD, no merge commit history +- **Description** — explain what, why, and how you tested + +--- + +## 10. Quality Validation + +Before submitting, verify your skill passes these checks: + +```bash +# Structure validation +python3 engineering/skill-tester/scripts/skill_validator.py --json + +# Quality scoring +python3 engineering/skill-tester/scripts/quality_scorer.py --json + +# Script testing (if you have scripts) +python3 engineering/skill-tester/scripts/script_tester.py --json + +# Security audit +python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py --strict +``` + +**Minimum requirements:** +- Structure score ≥ 75/100 +- All scripts pass `--help` +- Zero CRITICAL or HIGH security findings +- SKILL.md under 500 lines + +--- + +## Quick Reference + +| What | Rule | +|------|------| +| Frontmatter fields | `name` + `description` only | +| SKILL.md max lines | 500 | +| Python dependencies | stdlib only | +| PR target branch | `dev` | +| plugin.json author | Object `{"name": "...", "url": "..."}`, never string | +| External links in README | Not accepted | +| Skill count | 205 (do not change) | +| Commit format | Conventional commits | +| Script output | Must support `--json` | From 1ba7b77e34786efa48d1e0c5e2d4f3357424bad8 Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Thu, 26 Mar 2026 12:20:03 +0100 Subject: [PATCH 2/2] =?UTF-8?q?refactor(a11y-audit):=20extract=20inline=20?= =?UTF-8?q?content=20to=20reference=20files=20(41KB=20=E2=86=92=209.6KB)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md was 1,374 lines / 41KB — the largest in the repo, 2.7x above the 500-line Anthropic limit. Split into focused reference files. Trimmed: 1,374 → 211 lines (9.6KB) New reference files (6): - ci-cd-integration.md (GitHub Actions, GitLab CI, Azure DevOps, pre-commit) - audit-report-template.md (stakeholder report template) - testing-checklist.md (keyboard, screen reader, visual, forms) - color-contrast-guide.md (contrast checker, Tailwind palette, sr-only) - examples-by-framework.md (Vue, Angular, Next.js, Svelte examples) - wcag-22-new-criteria.md (WCAG 2.2 new success criteria) Appended to existing: - framework-a11y-patterns.md (fix patterns catalog added) Untouched: aria-patterns.md, wcag-quick-ref.md No content deleted — everything moved to references. Co-Authored-By: Claude Opus 4.6 (1M context) --- engineering-team/a11y-audit/SKILL.md | 1267 +---------------- .../references/audit-report-template.md | 46 + .../references/ci-cd-integration.md | 127 ++ .../references/color-contrast-guide.md | 83 ++ .../references/examples-by-framework.md | 312 ++++ .../references/framework-a11y-patterns.md | 338 +++++ .../references/testing-checklist.md | 41 + .../references/wcag-22-new-criteria.md | 79 + 8 files changed, 1078 insertions(+), 1215 deletions(-) create mode 100644 engineering-team/a11y-audit/references/audit-report-template.md create mode 100644 engineering-team/a11y-audit/references/ci-cd-integration.md create mode 100644 engineering-team/a11y-audit/references/color-contrast-guide.md create mode 100644 engineering-team/a11y-audit/references/examples-by-framework.md create mode 100644 engineering-team/a11y-audit/references/testing-checklist.md create mode 100644 engineering-team/a11y-audit/references/wcag-22-new-criteria.md diff --git a/engineering-team/a11y-audit/SKILL.md b/engineering-team/a11y-audit/SKILL.md index 3fbe103..fea8b43 100644 --- a/engineering-team/a11y-audit/SKILL.md +++ b/engineering-team/a11y-audit/SKILL.md @@ -1,41 +1,17 @@ --- -Name: a11y-audit -Tier: STANDARD -Category: engineering -Dependencies: none -Author: Alireza Rezvani -Version: 2.1.2 name: "a11y-audit" description: "Accessibility audit skill for scanning, fixing, and verifying WCAG 2.2 Level A and AA compliance across React, Next.js, Vue, Angular, Svelte, and plain HTML codebases. Use when auditing accessibility, fixing a11y violations, checking color contrast, generating compliance reports, or integrating accessibility checks into CI/CD pipelines." -license: MIT -metadata: - updated: 2026-03-18 --- # Accessibility Audit ---- - -**Name**: a11y-audit -**Tier**: STANDARD -**Category**: Engineering - Frontend Quality -**Dependencies**: Python 3.8+ (Standard Library Only) -**Author**: Alireza Rezvani -**Version**: 2.1.2 -**Last Updated**: 2026-03-18 -**License**: MIT - ---- - -## Name - -a11y-audit -- WCAG 2.2 Accessibility Audit and Remediation Skill +WCAG 2.2 Accessibility Audit and Remediation Skill ## Description The a11y-audit skill provides a complete accessibility audit pipeline for modern web applications. It implements a three-phase workflow -- Scan, Fix, Verify -- that identifies WCAG 2.2 Level A and AA violations, generates exact fix code per framework, and produces stakeholder-ready compliance reports. -This skill goes beyond detection. For every violation it finds, it provides the precise before/after code fix tailored to your framework (React, Next.js, Vue, Angular, Svelte, or plain HTML). It understands that a missing `alt` attribute on an `` in React JSX requires a different fix pattern than the same issue in a Vue SFC or an Angular template. +For every violation it finds, it provides the precise before/after code fix tailored to your framework (React, Next.js, Vue, Angular, Svelte, or plain HTML). **What this skill does:** @@ -45,18 +21,8 @@ This skill goes beyond detection. For every violation it finds, it provides the 4. **Reports** findings in a structured format suitable for developers, PMs, and compliance stakeholders 5. **Integrates** into CI/CD pipelines to prevent accessibility regressions -**Key differentiators:** - -- Framework-aware fix patterns (not generic HTML advice) -- Color contrast analysis with accessible alternative suggestions -- WCAG 2.2 coverage including the newest success criteria (Focus Appearance, Dragging Movements, Target Size) -- CI/CD pipeline integration with GitHub Actions, GitLab CI, and Azure DevOps -- Slash command support via `/a11y-audit` - ## Features -### Core Capabilities - | Feature | Description | |---------|-------------| | **Full WCAG 2.2 Scan** | Checks all Level A and AA success criteria across your codebase | @@ -64,37 +30,23 @@ This skill goes beyond detection. For every violation it finds, it provides the | **Severity Classification** | Categorizes each violation as Critical, Major, or Minor | | **Fix Code Generation** | Produces before/after code diffs for every issue | | **Color Contrast Checker** | Validates foreground/background pairs against AA and AAA ratios | -| **Accessible Alternatives** | Suggests replacement colors that meet contrast requirements | | **Compliance Reporting** | Generates stakeholder reports with pass/fail summaries | | **CI/CD Integration** | GitHub Actions, GitLab CI, Azure DevOps pipeline configs | | **Keyboard Navigation Audit** | Detects missing focus management and tab order issues | | **ARIA Validation** | Checks for incorrect, redundant, or missing ARIA attributes | -| **Live Region Detection** | Identifies dynamic content lacking `aria-live` announcements | -| **Form Accessibility** | Validates label associations, error messaging, and input types | - -### WCAG 2.2 Coverage Matrix - -| Principle | Level A Criteria | Level AA Criteria | -|-----------|-----------------|-------------------| -| **Perceivable** | 1.1.1 Non-text Content, 1.2.1-1.2.3 Time-based Media, 1.3.1-1.3.3 Adaptable, 1.4.1-1.4.2 Distinguishable | 1.3.4-1.3.5 Adaptable, 1.4.3-1.4.5 Contrast & Images of Text, 1.4.10-1.4.13 Reflow & Content | -| **Operable** | 2.1.1-2.1.2 Keyboard, 2.2.1-2.2.2 Timing, 2.3.1 Seizures, 2.4.1-2.4.4 Navigable, 2.5.1-2.5.4 Input | 2.4.5-2.4.7 Navigable, 2.4.11 Focus Appearance (NEW 2.2), 2.5.7 Dragging (NEW 2.2), 2.5.8 Target Size (NEW 2.2) | -| **Understandable** | 3.1.1 Language, 3.2.1-3.2.2 Predictable, 3.3.1-3.3.2 Input Assistance | 3.1.2 Language of Parts, 3.2.3-3.2.4 Predictable, 3.3.3-3.3.4 Error Handling, 3.3.7 Redundant Entry (NEW 2.2), 3.3.8 Accessible Auth (NEW 2.2) | -| **Robust** | 4.1.2 Name/Role/Value | 4.1.3 Status Messages | ### Severity Definitions | Severity | Definition | Example | SLA | |----------|-----------|---------|-----| -| **Critical** | Blocks access for entire user groups | Missing alt text on informational images, no keyboard access to primary navigation | Fix before release | -| **Major** | Significant barrier that degrades experience | Insufficient color contrast on body text, missing form labels | Fix within current sprint | +| **Critical** | Blocks access for entire user groups | Missing alt text, no keyboard access to navigation | Fix before release | +| **Major** | Significant barrier that degrades experience | Insufficient color contrast, missing form labels | Fix within current sprint | | **Minor** | Usability issue that causes friction | Redundant ARIA roles, suboptimal heading hierarchy | Fix within next 2 sprints | ## Usage ### Quick Start -Activate the skill and run an audit on your project: - ```bash # Scan entire project python scripts/a11y_scanner.py /path/to/project @@ -111,8 +63,6 @@ python scripts/contrast_checker.py --file /path/to/styles.css ### Slash Command -Use the `/a11y-audit` slash command for an interactive audit session: - ``` /a11y-audit # Audit current project /a11y-audit --scope src/ # Audit specific directory @@ -123,84 +73,23 @@ Use the `/a11y-audit` slash command for an interactive audit session: ### Three-Phase Workflow -#### Phase 1: Scan - -The scanner walks your source tree, detects the framework in use, and applies the appropriate rule set. +**Phase 1: Scan** -- Walk the source tree, detect framework, apply rule set. ```bash python scripts/a11y_scanner.py /path/to/project --format table ``` -**Sample output:** +**Phase 2: Fix** -- Apply framework-specific fixes for each violation. -``` -A11Y AUDIT REPORT - /path/to/project -Framework Detected: React (Next.js) -Files Scanned: 127 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +> See [references/framework-a11y-patterns.md](references/framework-a11y-patterns.md) for the complete fix patterns catalog. -CRITICAL (3 issues) - [1.1.1] src/components/Hero.tsx:14 - Missing alt text on element - [2.1.1] src/components/Modal.tsx:8 - Focus not trapped inside modal dialog - [1.4.3] src/styles/globals.css:42 - Contrast ratio 2.8:1 on .subtitle (requires 4.5:1) - -MAJOR (7 issues) - [2.4.11] src/components/Button.tsx:22 - Focus indicator not visible (2px outline required) - [1.3.1] src/components/Form.tsx:31 - Input missing associated