diff --git a/.agents/skills/skills_claude/SKILL.md b/.agents/skills/skills_claude/SKILL.md new file mode 100644 index 000000000..3640d6a4a --- /dev/null +++ b/.agents/skills/skills_claude/SKILL.md @@ -0,0 +1,338 @@ +--- +name: skills-claude-conventions +description: Development conventions and patterns for skills_claude. Python project with mixed commits. +--- + +# Skills Claude Conventions + +> Generated from [Eaprime1/skills_claude](https://github.com/Eaprime1/skills_claude) on 2026-03-24 + +## Overview + +This skill teaches Claude the development patterns and conventions used in skills_claude. + +## Tech Stack + +- **Primary Language**: Python +- **Architecture**: hybrid module organization +- **Test Location**: separate + +## When to Use This Skill + +Activate this skill when: +- Making changes to this repository +- Adding new features following established patterns +- Writing tests that match project conventions +- Creating commits with proper message format + +## Commit Conventions + +Follow these commit message conventions based on 42 analyzed commits. + +### Commit Style: Mixed Style + +### Prefixes Used + +- `feat` +- `chore` + +### Message Guidelines + +- Average message length: ~56 characters +- Keep first line concise and descriptive +- Use imperative mood ("Add feature" not "Added feature") + + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/update-or-export-example-skills.md) +``` + +*Commit message example* + +```text +chore: update claude-api skill [auto-sync] (#729) +``` + +*Commit message example* + +```text +Merge branch 'anthropics:main' into claude/skills-brainstorm-Nd4vz +``` + +*Commit message example* + +```text +Merge pull request #2 from Eaprime1/ecc-tools/skills_claude-1774393541560 +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/add-new-skill.md) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/feature-development.md) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.codex/agents/docs-researcher.toml) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.codex/agents/reviewer.toml) +``` + +## Architecture + +### Project Structure: Single Package + +This project uses **hybrid** module organization. + +### Guidelines + +- This project uses a hybrid organization +- Follow existing patterns when adding new code + +## Code Style + +### Language: Python + +### Naming Conventions + +| Element | Convention | +|---------|------------| +| Files | kebab-case | +| Functions | camelCase | +| Classes | PascalCase | +| Constants | SCREAMING_SNAKE_CASE | + +### Import Style: Relative Imports + +### Export Style: Named Exports + + +*Preferred import style* + +```typescript +// Use relative imports +import { Button } from '../components/Button' +import { useAuth } from './hooks/useAuth' +``` + +*Preferred export style* + +```typescript +// Use named exports +export function calculateTotal() { ... } +export const TAX_RATE = 0.1 +export interface Order { ... } +``` + +## Common Workflows + +These workflows were detected from analyzing commit patterns. + +### Feature Development + +Standard feature implementation workflow + +**Frequency**: ~19 times per month + +**Steps**: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +**Files typically involved**: +- `**/*.test.*` +- `**/api/**` + +**Example commit sequence**: +``` +Add 3rd Party notices (#4) +Add initial Agent Skills Spec (#2) +Small tweak to blog link (#7) +``` + +### Refactoring + +Code refactoring and cleanup workflow + +**Frequency**: ~2 times per month + +**Steps**: +1. Ensure tests pass before refactor +2. Refactor code structure +3. Verify tests still pass + +**Files typically involved**: +- `src/**/*` + +**Example commit sequence**: +``` +Reorganize the example skills (#1) +Adding more details to README (#3) +Add 3rd Party notices (#4) +``` + +### Add Or Update Skill + +Adds a new skill or updates an existing skill, including its SKILL.md and related scripts/assets. + +**Frequency**: ~2 times per month + +**Steps**: +1. Create or update SKILL.md in skills// +2. Add or update supporting scripts, templates, or assets in the skill's folder +3. If applicable, update marketplace or index files (e.g., .claude-plugin/marketplace.json) +4. Optionally, add language-specific guides or reference files + +**Files typically involved**: +- `skills/*/SKILL.md` +- `skills/*/scripts/*.py` +- `skills/*/templates/*` +- `skills/*/reference/*` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Create or update SKILL.md in skills// +Add or update supporting scripts, templates, or assets in the skill's folder +If applicable, update marketplace or index files (e.g., .claude-plugin/marketplace.json) +Optionally, add language-specific guides or reference files +``` + +### Export Or Bundle Skills + +Exports multiple skills as distributable bundles or updates the exported set of skills. + +**Frequency**: ~1 times per month + +**Steps**: +1. Aggregate or update SKILL.md and related files for all relevant skills +2. Generate distributable bundles (e.g., .skill files in dist/) +3. Update index/marketplace files if needed + +**Files typically involved**: +- `dist/*.skill` +- `skills/*/SKILL.md` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Aggregate or update SKILL.md and related files for all relevant skills +Generate distributable bundles (e.g., .skill files in dist/) +Update index/marketplace files if needed +``` + +### Office Skill Shared Module Update + +Updates or reorganizes shared Office document processing modules (docx, pptx, xlsx) and their schemas/scripts. + +**Frequency**: ~1 times per month + +**Steps**: +1. Update or reorganize scripts in skills/{docx,pptx,xlsx}/scripts/office/ +2. Update or add schemas in skills/{docx,pptx,xlsx}/scripts/office/schemas/ +3. Update pack/unpack/validate scripts for each Office skill +4. Optionally, update SKILL.md or documentation for each skill + +**Files typically involved**: +- `skills/docx/scripts/office/**/*` +- `skills/pptx/scripts/office/**/*` +- `skills/xlsx/scripts/office/**/*` +- `skills/docx/scripts/office/schemas/**/*` +- `skills/pptx/scripts/office/schemas/**/*` +- `skills/xlsx/scripts/office/schemas/**/*` +- `skills/docx/scripts/office/pack.py` +- `skills/pptx/scripts/office/pack.py` +- `skills/xlsx/scripts/office/pack.py` +- `skills/docx/SKILL.md` +- `skills/pptx/SKILL.md` +- `skills/xlsx/SKILL.md` + +**Example commit sequence**: +``` +Update or reorganize scripts in skills/{docx,pptx,xlsx}/scripts/office/ +Update or add schemas in skills/{docx,pptx,xlsx}/scripts/office/schemas/ +Update pack/unpack/validate scripts for each Office skill +Optionally, update SKILL.md or documentation for each skill +``` + +### Skill Creator Tooling Update + +Updates scripts, references, or documentation in the skill-creator tool, including validation, packaging, and optimization scripts. + +**Frequency**: ~1 times per month + +**Steps**: +1. Update or add scripts in skills/skill-creator/scripts/ +2. Update references or documentation in skills/skill-creator/references/ +3. Update SKILL.md for skill-creator if needed + +**Files typically involved**: +- `skills/skill-creator/scripts/*.py` +- `skills/skill-creator/references/*.md` +- `skills/skill-creator/SKILL.md` + +**Example commit sequence**: +``` +Update or add scripts in skills/skill-creator/scripts/ +Update references or documentation in skills/skill-creator/references/ +Update SKILL.md for skill-creator if needed +``` + +### Add Or Update Claude Api Skill + +Adds or updates the claude-api documentation skill, including language-specific guides and shared references. + +**Frequency**: ~1 times per month + +**Steps**: +1. Add or update skills/claude-api/SKILL.md +2. Add or update language guides in skills/claude-api/{python,typescript,java,go,ruby,csharp,php,curl}/ +3. Update shared documentation in skills/claude-api/shared/ +4. Update marketplace or index if needed + +**Files typically involved**: +- `skills/claude-api/SKILL.md` +- `skills/claude-api/*/claude-api.md` +- `skills/claude-api/*/README.md` +- `skills/claude-api/*/*.md` +- `skills/claude-api/shared/*.md` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Add or update skills/claude-api/SKILL.md +Add or update language guides in skills/claude-api/{python,typescript,java,go,ruby,csharp,php,curl}/ +Update shared documentation in skills/claude-api/shared/ +Update marketplace or index if needed +``` + + +## Best Practices + +Based on analysis of the codebase, follow these practices: + +### Do + +- Use kebab-case for file names +- Prefer named exports + +### Don't + +- Don't deviate from established patterns without discussion + +--- + +*This skill was auto-generated by [ECC Tools](https://ecc.tools). Review and customize as needed for your team.* diff --git a/.agents/skills/skills_claude/agents/openai.yaml b/.agents/skills/skills_claude/agents/openai.yaml new file mode 100644 index 000000000..6b23ac58f --- /dev/null +++ b/.agents/skills/skills_claude/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Skills Claude" + short_description: "Repo-specific patterns and workflows for skills_claude" + default_prompt: "Use the skills_claude repo skill to follow existing architecture, testing, and workflow conventions." +policy: + allow_implicit_invocation: true \ No newline at end of file diff --git a/.claude/commands/add-new-skill.md b/.claude/commands/add-new-skill.md new file mode 100644 index 000000000..e4ee5b190 --- /dev/null +++ b/.claude/commands/add-new-skill.md @@ -0,0 +1,41 @@ +--- +name: add-new-skill +description: Workflow command scaffold for add-new-skill in skills_claude. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-new-skill + +Use this workflow when working on **add-new-skill** in `skills_claude`. + +## Goal + +Adds a new skill to the repository, including its SKILL.md and any supporting files. + +## Common Files + +- `skills/*/SKILL.md` +- `skills/*/LICENSE.txt` +- `skills/*/scripts/*` +- `skills/*/templates/*` +- `skills/*/examples/*` +- `skills/*/reference/*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Create a new folder under skills/ (or previously examples/, document-skills/, office-examples/). +- Add SKILL.md to the new skill folder. +- Optionally add LICENSE.txt, scripts/, templates/, examples/, or reference/ subfolders and files as needed. +- Update skills/README.md or .claude-plugin/marketplace.json if necessary. + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/add-or-update-skill.md b/.claude/commands/add-or-update-skill.md new file mode 100644 index 000000000..c507405fa --- /dev/null +++ b/.claude/commands/add-or-update-skill.md @@ -0,0 +1,40 @@ +--- +name: add-or-update-skill +description: Workflow command scaffold for add-or-update-skill in skills_claude. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-or-update-skill + +Use this workflow when working on **add-or-update-skill** in `skills_claude`. + +## Goal + +Adds a new skill or updates an existing skill, including its SKILL.md and related scripts/assets. + +## Common Files + +- `skills/*/SKILL.md` +- `skills/*/scripts/*.py` +- `skills/*/templates/*` +- `skills/*/reference/*` +- `.claude-plugin/marketplace.json` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Create or update SKILL.md in skills// +- Add or update supporting scripts, templates, or assets in the skill's folder +- If applicable, update marketplace or index files (e.g., .claude-plugin/marketplace.json) +- Optionally, add language-specific guides or reference files + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/feature-development.md b/.claude/commands/feature-development.md new file mode 100644 index 000000000..70704fd43 --- /dev/null +++ b/.claude/commands/feature-development.md @@ -0,0 +1,36 @@ +--- +name: feature-development +description: Workflow command scaffold for feature-development in skills_claude. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development + +Use this workflow when working on **feature-development** in `skills_claude`. + +## Goal + +Standard feature implementation workflow + +## Common Files + +- `**/*.test.*` +- `**/api/**` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Add feature implementation +- Add tests for feature +- Update documentation + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/refactoring.md b/.claude/commands/refactoring.md new file mode 100644 index 000000000..7ccd6579f --- /dev/null +++ b/.claude/commands/refactoring.md @@ -0,0 +1,35 @@ +--- +name: refactoring +description: Workflow command scaffold for refactoring in skills_claude. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /refactoring + +Use this workflow when working on **refactoring** in `skills_claude`. + +## Goal + +Code refactoring and cleanup workflow + +## Common Files + +- `src/**/*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Ensure tests pass before refactor +- Refactor code structure +- Verify tests still pass + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/update-or-export-example-skills.md b/.claude/commands/update-or-export-example-skills.md new file mode 100644 index 000000000..f7f724e53 --- /dev/null +++ b/.claude/commands/update-or-export-example-skills.md @@ -0,0 +1,40 @@ +--- +name: update-or-export-example-skills +description: Workflow command scaffold for update-or-export-example-skills in skills_claude. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /update-or-export-example-skills + +Use this workflow when working on **update-or-export-example-skills** in `skills_claude`. + +## Goal + +Bulk updates or exports of example skills, often including renaming, reorganizing, or synchronizing multiple skill folders and their contents. + +## Common Files + +- `skills/*/SKILL.md` +- `skills/*/LICENSE.txt` +- `skills/*/scripts/*` +- `skills/*/templates/*` +- `skills/*/examples/*` +- `skills/*/reference/*` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Modify, move, or rename multiple skill folders (e.g., from examples/ to skills/, or document-skills/). +- Update SKILL.md and supporting files for each skill. +- Update marketplace.json or skills/README.md as needed. + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json new file mode 100644 index 000000000..b5f8b6e99 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,240 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-03-24T23:11:26.356Z", + "repo": "https://github.com/Eaprime1/skills_claude", + "profiles": { + "requested": "research", + "recommended": "research", + "effective": "developer", + "requestedAlias": "research", + "recommendedAlias": "research", + "effectiveAlias": "developer" + }, + "requestedProfile": "research", + "profile": "developer", + "recommendedProfile": "research", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation", + "research-tooling" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [ + "research-tooling" + ], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [ + "research-pack" + ], + "tierFilteredPackages": [ + "research-pack" + ], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack", + "research-pack" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/skills_claude-instincts.yaml", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-or-update-skill.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/skills_claude-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-or-update-skill.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/SKILL.md", + ".agents/skills/skills_claude/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/skills_claude-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-or-update-skill.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/skills_claude/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/skills_claude/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/skills_claude/agents/openai.yaml", + "description": "Codex skill metadata so the repo skill appears cleanly in the skill interface." + }, + { + "moduleId": "runtime-core", + "path": ".claude/identity.json", + "description": "Suggested identity.json baseline derived from repository conventions." + }, + { + "moduleId": "runtime-core", + "path": ".codex/config.toml", + "description": "Repo-local Codex MCP and multi-agent baseline aligned with ECC defaults." + }, + { + "moduleId": "runtime-core", + "path": ".codex/AGENTS.md", + "description": "Codex usage guide that points at the generated repo skill and workflow bundle." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/explorer.toml", + "description": "Read-only explorer role config for Codex multi-agent work." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/reviewer.toml", + "description": "Read-only reviewer role config focused on correctness and security." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/docs-researcher.toml", + "description": "Read-only docs researcher role config for API verification." + }, + { + "moduleId": "runtime-core", + "path": ".claude/homunculus/instincts/inherited/skills_claude-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development.md", + "description": "Workflow command scaffold for feature-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/refactoring.md", + "description": "Workflow command scaffold for refactoring." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-or-update-skill.md", + "description": "Workflow command scaffold for add-or-update-skill." + } + ], + "workflows": [ + { + "command": "feature-development", + "path": ".claude/commands/feature-development.md" + }, + { + "command": "refactoring", + "path": ".claude/commands/refactoring.md" + }, + { + "command": "add-or-update-skill", + "path": ".claude/commands/add-or-update-skill.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/skills_claude/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md", + ".claude/commands/add-or-update-skill.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/skills_claude/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/skills_claude-instincts.yaml b/.claude/homunculus/instincts/inherited/skills_claude-instincts.yaml new file mode 100644 index 000000000..e50e1aa5b --- /dev/null +++ b/.claude/homunculus/instincts/inherited/skills_claude-instincts.yaml @@ -0,0 +1,227 @@ +# Instincts generated from https://github.com/Eaprime1/skills_claude +# Generated: 2026-03-24T23:05:41.152Z +# Version: 2.0 +# NOTE: This file supplements (does not replace) any existing curated instincts. +# High-confidence manually curated instincts should be preserved alongside these. + +--- +id: skills_claude-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Commit Length + +## Action + +Keep commit messages concise (~46 characters) + +## Evidence + +- Average commit message length: 46 chars +- Based on 19 commits + +--- +id: skills_claude-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Naming Files + +## Action + +Use kebab-case naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: kebab-case + +--- +id: skills_claude-import-relative +trigger: "when importing modules" +confidence: 0.75 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Import Relative + +## Action + +Use relative imports for project files + +## Evidence + +- Import analysis shows relative import pattern +- Example: import { x } from '../lib/x' + +--- +id: skills_claude-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: skills_claude-test-separate +trigger: "when writing tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Test Separate + +## Action + +Place tests in the tests/ or __tests__/ directory, mirroring src structure + +## Evidence + +- Separate test directory pattern detected +- Tests live in dedicated test folders + +--- +id: skills_claude-workflow-feature-development +trigger: "when implementing a new feature" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Workflow Feature Development + +## Action + +Follow the feature-development workflow: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~13x per month +- Files: **/*.test.* + +--- +id: skills_claude-workflow-add-new-skill +trigger: "when doing add new skill" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Workflow Add New Skill + +## Action + +Follow the add-new-skill workflow: +1. Create a new folder under skills/ (or previously examples/, document-skills/, office-examples/). +2. Add SKILL.md to the new skill folder. +3. Optionally add LICENSE.txt, scripts/, templates/, examples/, or reference/ subfolders and files as needed. +4. Update skills/README.md or .claude-plugin/marketplace.json if necessary. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: skills/*/SKILL.md, skills/*/LICENSE.txt, skills/*/scripts/* + +--- +id: skills_claude-workflow-update-or-export-example-skills +trigger: "when doing update or export example skills" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Workflow Update Or Export Example Skills + +## Action + +Follow the update-or-export-example-skills workflow: +1. Modify, move, or rename multiple skill folders (e.g., from examples/ to skills/, or document-skills/). +2. Update SKILL.md and supporting files for each skill. +3. Update marketplace.json or skills/README.md as needed. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: skills/*/SKILL.md, skills/*/LICENSE.txt, skills/*/scripts/* + +--- +id: skills_claude-workflow-package-skills-for-distribution +trigger: "when doing package skills for distribution" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Workflow Package Skills For Distribution + +## Action + +Follow the package-skills-for-distribution workflow: +1. Run packaging scripts or commands. +2. Generate .skill files in the dist/ directory. +3. Ensure SKILL.md and all necessary assets are included in each .skill file. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: dist/*.skill, skills/*/SKILL.md, skills/*/scripts/* + +--- +id: skills_claude-workflow-update-spec-or-documentation +trigger: "when doing update spec or documentation" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/Eaprime1/skills_claude +--- + +# Skills_claude Workflow Update Spec Or Documentation + +## Action + +Follow the update-spec-or-documentation workflow: +1. Edit spec/agent-skills-spec.md or related spec/*.md files. +2. Optionally split or merge documentation files. +3. Update README.md with new links or notes. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: spec/agent-skills-spec.md, spec/skill-authoring.md, spec/skill-client-integration.md + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 000000000..408095e5a --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "moderate", + "codeComments": true, + "explanations": true + }, + "domains": [ + "python" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-03-24T23:11:41.389Z" +} \ No newline at end of file diff --git a/.claude/skills/skills_claude/SKILL.md b/.claude/skills/skills_claude/SKILL.md new file mode 100644 index 000000000..3640d6a4a --- /dev/null +++ b/.claude/skills/skills_claude/SKILL.md @@ -0,0 +1,338 @@ +--- +name: skills-claude-conventions +description: Development conventions and patterns for skills_claude. Python project with mixed commits. +--- + +# Skills Claude Conventions + +> Generated from [Eaprime1/skills_claude](https://github.com/Eaprime1/skills_claude) on 2026-03-24 + +## Overview + +This skill teaches Claude the development patterns and conventions used in skills_claude. + +## Tech Stack + +- **Primary Language**: Python +- **Architecture**: hybrid module organization +- **Test Location**: separate + +## When to Use This Skill + +Activate this skill when: +- Making changes to this repository +- Adding new features following established patterns +- Writing tests that match project conventions +- Creating commits with proper message format + +## Commit Conventions + +Follow these commit message conventions based on 42 analyzed commits. + +### Commit Style: Mixed Style + +### Prefixes Used + +- `feat` +- `chore` + +### Message Guidelines + +- Average message length: ~56 characters +- Keep first line concise and descriptive +- Use imperative mood ("Add feature" not "Added feature") + + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/update-or-export-example-skills.md) +``` + +*Commit message example* + +```text +chore: update claude-api skill [auto-sync] (#729) +``` + +*Commit message example* + +```text +Merge branch 'anthropics:main' into claude/skills-brainstorm-Nd4vz +``` + +*Commit message example* + +```text +Merge pull request #2 from Eaprime1/ecc-tools/skills_claude-1774393541560 +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/add-new-skill.md) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.claude/commands/feature-development.md) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.codex/agents/docs-researcher.toml) +``` + +*Commit message example* + +```text +feat: add skills_claude ECC bundle (.codex/agents/reviewer.toml) +``` + +## Architecture + +### Project Structure: Single Package + +This project uses **hybrid** module organization. + +### Guidelines + +- This project uses a hybrid organization +- Follow existing patterns when adding new code + +## Code Style + +### Language: Python + +### Naming Conventions + +| Element | Convention | +|---------|------------| +| Files | kebab-case | +| Functions | camelCase | +| Classes | PascalCase | +| Constants | SCREAMING_SNAKE_CASE | + +### Import Style: Relative Imports + +### Export Style: Named Exports + + +*Preferred import style* + +```typescript +// Use relative imports +import { Button } from '../components/Button' +import { useAuth } from './hooks/useAuth' +``` + +*Preferred export style* + +```typescript +// Use named exports +export function calculateTotal() { ... } +export const TAX_RATE = 0.1 +export interface Order { ... } +``` + +## Common Workflows + +These workflows were detected from analyzing commit patterns. + +### Feature Development + +Standard feature implementation workflow + +**Frequency**: ~19 times per month + +**Steps**: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +**Files typically involved**: +- `**/*.test.*` +- `**/api/**` + +**Example commit sequence**: +``` +Add 3rd Party notices (#4) +Add initial Agent Skills Spec (#2) +Small tweak to blog link (#7) +``` + +### Refactoring + +Code refactoring and cleanup workflow + +**Frequency**: ~2 times per month + +**Steps**: +1. Ensure tests pass before refactor +2. Refactor code structure +3. Verify tests still pass + +**Files typically involved**: +- `src/**/*` + +**Example commit sequence**: +``` +Reorganize the example skills (#1) +Adding more details to README (#3) +Add 3rd Party notices (#4) +``` + +### Add Or Update Skill + +Adds a new skill or updates an existing skill, including its SKILL.md and related scripts/assets. + +**Frequency**: ~2 times per month + +**Steps**: +1. Create or update SKILL.md in skills// +2. Add or update supporting scripts, templates, or assets in the skill's folder +3. If applicable, update marketplace or index files (e.g., .claude-plugin/marketplace.json) +4. Optionally, add language-specific guides or reference files + +**Files typically involved**: +- `skills/*/SKILL.md` +- `skills/*/scripts/*.py` +- `skills/*/templates/*` +- `skills/*/reference/*` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Create or update SKILL.md in skills// +Add or update supporting scripts, templates, or assets in the skill's folder +If applicable, update marketplace or index files (e.g., .claude-plugin/marketplace.json) +Optionally, add language-specific guides or reference files +``` + +### Export Or Bundle Skills + +Exports multiple skills as distributable bundles or updates the exported set of skills. + +**Frequency**: ~1 times per month + +**Steps**: +1. Aggregate or update SKILL.md and related files for all relevant skills +2. Generate distributable bundles (e.g., .skill files in dist/) +3. Update index/marketplace files if needed + +**Files typically involved**: +- `dist/*.skill` +- `skills/*/SKILL.md` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Aggregate or update SKILL.md and related files for all relevant skills +Generate distributable bundles (e.g., .skill files in dist/) +Update index/marketplace files if needed +``` + +### Office Skill Shared Module Update + +Updates or reorganizes shared Office document processing modules (docx, pptx, xlsx) and their schemas/scripts. + +**Frequency**: ~1 times per month + +**Steps**: +1. Update or reorganize scripts in skills/{docx,pptx,xlsx}/scripts/office/ +2. Update or add schemas in skills/{docx,pptx,xlsx}/scripts/office/schemas/ +3. Update pack/unpack/validate scripts for each Office skill +4. Optionally, update SKILL.md or documentation for each skill + +**Files typically involved**: +- `skills/docx/scripts/office/**/*` +- `skills/pptx/scripts/office/**/*` +- `skills/xlsx/scripts/office/**/*` +- `skills/docx/scripts/office/schemas/**/*` +- `skills/pptx/scripts/office/schemas/**/*` +- `skills/xlsx/scripts/office/schemas/**/*` +- `skills/docx/scripts/office/pack.py` +- `skills/pptx/scripts/office/pack.py` +- `skills/xlsx/scripts/office/pack.py` +- `skills/docx/SKILL.md` +- `skills/pptx/SKILL.md` +- `skills/xlsx/SKILL.md` + +**Example commit sequence**: +``` +Update or reorganize scripts in skills/{docx,pptx,xlsx}/scripts/office/ +Update or add schemas in skills/{docx,pptx,xlsx}/scripts/office/schemas/ +Update pack/unpack/validate scripts for each Office skill +Optionally, update SKILL.md or documentation for each skill +``` + +### Skill Creator Tooling Update + +Updates scripts, references, or documentation in the skill-creator tool, including validation, packaging, and optimization scripts. + +**Frequency**: ~1 times per month + +**Steps**: +1. Update or add scripts in skills/skill-creator/scripts/ +2. Update references or documentation in skills/skill-creator/references/ +3. Update SKILL.md for skill-creator if needed + +**Files typically involved**: +- `skills/skill-creator/scripts/*.py` +- `skills/skill-creator/references/*.md` +- `skills/skill-creator/SKILL.md` + +**Example commit sequence**: +``` +Update or add scripts in skills/skill-creator/scripts/ +Update references or documentation in skills/skill-creator/references/ +Update SKILL.md for skill-creator if needed +``` + +### Add Or Update Claude Api Skill + +Adds or updates the claude-api documentation skill, including language-specific guides and shared references. + +**Frequency**: ~1 times per month + +**Steps**: +1. Add or update skills/claude-api/SKILL.md +2. Add or update language guides in skills/claude-api/{python,typescript,java,go,ruby,csharp,php,curl}/ +3. Update shared documentation in skills/claude-api/shared/ +4. Update marketplace or index if needed + +**Files typically involved**: +- `skills/claude-api/SKILL.md` +- `skills/claude-api/*/claude-api.md` +- `skills/claude-api/*/README.md` +- `skills/claude-api/*/*.md` +- `skills/claude-api/shared/*.md` +- `.claude-plugin/marketplace.json` + +**Example commit sequence**: +``` +Add or update skills/claude-api/SKILL.md +Add or update language guides in skills/claude-api/{python,typescript,java,go,ruby,csharp,php,curl}/ +Update shared documentation in skills/claude-api/shared/ +Update marketplace or index if needed +``` + + +## Best Practices + +Based on analysis of the codebase, follow these practices: + +### Do + +- Use kebab-case for file names +- Prefer named exports + +### Don't + +- Don't deviate from established patterns without discussion + +--- + +*This skill was auto-generated by [ECC Tools](https://ecc.tools). Review and customize as needed for your team.* diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 000000000..a7a340fba --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,28 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/skills_claude/SKILL.md` +- Claude-facing companion skill: `.claude/skills/skills_claude/SKILL.md` +- Keep user-specific credentials and private MCPs in `~/.codex/config.toml`, not in this repo. + +## MCP Baseline + +Treat `.codex/config.toml` as the default ECC-safe baseline for work in this repository. +The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking. + +## Multi-Agent Support + +- Explorer: read-only evidence gathering +- Reviewer: correctness, security, and regression review +- Docs researcher: API and release-note verification + +## Workflow Files + +- `.claude/commands/feature-development.md` +- `.claude/commands/add-new-skill.md` +- `.claude/commands/update-or-export-example-skills.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 000000000..0daae570b --- /dev/null +++ b/.codex/agents/docs-researcher.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Verify APIs, framework behavior, and release-note claims against primary documentation before changes land. +Cite the exact docs or file paths that support each claim. +Do not invent undocumented behavior. +""" \ No newline at end of file diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 000000000..732df7aff --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Stay in exploration mode. +Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. +Prefer targeted search and file reads over broad scans. +""" \ No newline at end of file diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 000000000..b13ed9cf1 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "high" +sandbox_mode = "read-only" + +developer_instructions = """ +Review like an owner. +Prioritize correctness, security, behavioral regressions, and missing tests. +Lead with concrete findings and avoid style-only feedback unless it hides a real bug. +""" \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 000000000..bc1ee67f6 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,48 @@ +#:schema https://developers.openai.com/codex/config-schema.json + +# ECC Tools generated Codex baseline +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "live" + +[mcp_servers.github] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp@latest"] + +[mcp_servers.exa] +url = "https://mcp.exa.ai/mcp" + +[mcp_servers.memory] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-memory"] + +[mcp_servers.playwright] +command = "npx" +args = ["-y", "@playwright/mcp@latest", "--extension"] + +[mcp_servers.sequential-thinking] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-sequential-thinking"] + +[features] +multi_agent = true + +[agents] +max_threads = 6 +max_depth = 1 + +[agents.explorer] +description = "Read-only codebase explorer for gathering evidence before changes are proposed." +config_file = "agents/explorer.toml" + +[agents.reviewer] +description = "PR reviewer focused on correctness, security, and missing tests." +config_file = "agents/reviewer.toml" + +[agents.docs_researcher] +description = "Documentation specialist that verifies APIs, framework behavior, and release notes." +config_file = "agents/docs-researcher.toml" \ No newline at end of file diff --git a/dist/a11y-auditor.skill b/dist/a11y-auditor.skill new file mode 100644 index 000000000..ae6c4e6ad Binary files /dev/null and b/dist/a11y-auditor.skill differ diff --git a/dist/changelog-curator.skill b/dist/changelog-curator.skill new file mode 100644 index 000000000..28399c512 Binary files /dev/null and b/dist/changelog-curator.skill differ diff --git a/dist/code-review-guide.skill b/dist/code-review-guide.skill new file mode 100644 index 000000000..0d8844322 Binary files /dev/null and b/dist/code-review-guide.skill differ diff --git a/dist/data-storytelling.skill b/dist/data-storytelling.skill new file mode 100644 index 000000000..a9ceb0621 Binary files /dev/null and b/dist/data-storytelling.skill differ diff --git a/dist/github-actions-builder.skill b/dist/github-actions-builder.skill new file mode 100644 index 000000000..630630b3a Binary files /dev/null and b/dist/github-actions-builder.skill differ diff --git a/dist/quiz-generator.skill b/dist/quiz-generator.skill new file mode 100644 index 000000000..979c0d51b Binary files /dev/null and b/dist/quiz-generator.skill differ diff --git a/dist/rfc-architect.skill b/dist/rfc-architect.skill new file mode 100644 index 000000000..69cc60f88 Binary files /dev/null and b/dist/rfc-architect.skill differ diff --git a/dist/tutorial-builder.skill b/dist/tutorial-builder.skill new file mode 100644 index 000000000..befc60e2e Binary files /dev/null and b/dist/tutorial-builder.skill differ diff --git a/skills/a11y-auditor/SKILL.md b/skills/a11y-auditor/SKILL.md new file mode 100644 index 000000000..5410e14a5 --- /dev/null +++ b/skills/a11y-auditor/SKILL.md @@ -0,0 +1,252 @@ +--- +name: a11y-auditor +description: Accessibility audit guidance and WCAG compliance checking. Use when users need to evaluate web content accessibility, check WCAG compliance, review for screen reader compatibility, audit color contrast, assess keyboard navigation, or improve accessibility of digital content. Triggers on requests like "check accessibility", "WCAG audit", "screen reader compatible", "accessibility review", "ADA compliance", or "a11y check". +--- + +# Accessibility Auditor + +Guide accessibility evaluations using WCAG standards as the reality benchmark for validation. + +## WCAG Quick Reference + +### Conformance Levels + +| Level | Meaning | Typical Requirement | +|-------|---------|---------------------| +| **A** | Minimum | Legal baseline in most jurisdictions | +| **AA** | Standard | Most common compliance target | +| **AAA** | Enhanced | Specialized contexts (government, healthcare) | + +### Four Principles (POUR) + +1. **Perceivable** - Information must be presentable to users +2. **Operable** - Interface must be navigable and usable +3. **Understandable** - Content and operation must be clear +4. **Robust** - Content must work with assistive technologies + +## Audit Checklist by Category + +### 1. Text Alternatives (WCAG 1.1) + +**Images** +- [ ] All `` have `alt` attributes +- [ ] Decorative images use `alt=""` or CSS background +- [ ] Complex images have extended descriptions +- [ ] Alt text describes function, not appearance + +**Verification:** +``` +Check: Does alt text answer "What information does this image convey?" +Pass: "Submit button" or "Company logo linking to homepage" +Fail: "image.jpg" or "picture of a button" +``` + +### 2. Time-Based Media (WCAG 1.2) + +- [ ] Videos have captions +- [ ] Audio has transcripts +- [ ] Live audio has real-time captions (AA) +- [ ] Audio descriptions for visual-only content (AA) + +### 3. Adaptable Content (WCAG 1.3) + +**Structure** +- [ ] Headings in logical order (h1 → h2 → h3) +- [ ] Lists use proper `
    `, `
      `, `
      ` markup +- [ ] Tables have headers (``) and scope +- [ ] Forms have associated labels + +**Verification:** +``` +Test: Read content with CSS disabled +Pass: Content order and structure still make sense +Fail: Content becomes jumbled or loses meaning +``` + +### 4. Distinguishable Content (WCAG 1.4) + +**Color Contrast** + +| Text Type | AA Requirement | AAA Requirement | +|-----------|----------------|-----------------| +| Normal text | 4.5:1 | 7:1 | +| Large text (18pt+) | 3:1 | 4.5:1 | +| UI components | 3:1 | 3:1 | + +- [ ] Text meets contrast ratios +- [ ] Color is not only indicator of meaning +- [ ] Text resizes to 200% without loss +- [ ] No horizontal scroll at 320px width (AA) + +**Verification:** +``` +Tool: Use contrast checker (WebAIM, Colour Contrast Analyser) +Test: View in grayscale - is all information still clear? +``` + +### 5. Keyboard Accessible (WCAG 2.1) + +- [ ] All functions available via keyboard +- [ ] No keyboard traps +- [ ] Focus order is logical +- [ ] Focus indicator is visible +- [ ] Skip navigation link present + +**Verification:** +``` +Test: Unplug mouse, navigate entire site using only: +- Tab / Shift+Tab (move focus) +- Enter / Space (activate) +- Arrow keys (within components) +- Escape (close dialogs) + +Pass: Can access all content and functions +Fail: Any element unreachable or traps focus +``` + +### 6. Timing (WCAG 2.2) + +- [ ] Time limits can be extended or disabled +- [ ] Auto-updating content can be paused +- [ ] No content flashes more than 3 times/second + +### 7. Navigation (WCAG 2.4) + +- [ ] Pages have descriptive titles +- [ ] Focus order matches visual order +- [ ] Link purpose clear from text (or context) +- [ ] Multiple ways to find pages (AA) +- [ ] Headings and labels are descriptive + +**Verification:** +``` +Test: Read only the links on a page +Pass: Each link makes sense out of context +Fail: "Click here", "Read more", "Link" without context +``` + +### 8. Input Modalities (WCAG 2.5) + +- [ ] Touch targets at least 44x44 CSS pixels +- [ ] Gestures have alternatives +- [ ] Labels match accessible names + +### 9. Readable Content (WCAG 3.1) + +- [ ] Page language declared (`lang` attribute) +- [ ] Language changes marked in content +- [ ] Unusual words/abbreviations explained + +### 10. Predictable Behavior (WCAG 3.2) + +- [ ] Focus doesn't trigger unexpected changes +- [ ] Input doesn't trigger unexpected changes +- [ ] Navigation is consistent across pages + +### 11. Input Assistance (WCAG 3.3) + +- [ ] Errors clearly identified +- [ ] Error suggestions provided +- [ ] Labels/instructions for input +- [ ] Error prevention for legal/financial (AA) + +**Verification:** +``` +Test: Submit forms with errors intentionally +Pass: Error messages are specific and adjacent to field +Fail: Generic "Form error" or error at page top only +``` + +### 12. Compatible Markup (WCAG 4.1) + +- [ ] Valid HTML (no duplicate IDs) +- [ ] ARIA used correctly +- [ ] Custom components have proper roles +- [ ] Status messages announced (AA) + +## Screen Reader Testing + +### Quick Test Protocol + +1. **Headings navigation**: Press `H` to jump between headings +2. **Links list**: View all links (should make sense) +3. **Forms mode**: Tab through form, verify labels read +4. **Images**: Confirm alt text is appropriate +5. **Dynamic content**: Check live regions announce updates + +### Common Screen Readers + +| Platform | Screen Reader | Key Commands | +|----------|---------------|--------------| +| Windows | NVDA (free) | Insert = NVDA key | +| Windows | JAWS | Insert = JAWS key | +| macOS/iOS | VoiceOver | VO = Ctrl+Option | +| Android | TalkBack | Swipe gestures | + +## Automated Testing Tools + +### Integrate in Workflow + +```bash +# Axe-core (CLI) +npx @axe-core/cli https://example.com + +# Pa11y +npx pa11y https://example.com + +# Lighthouse (Chrome) +lighthouse --only-categories=accessibility https://example.com +``` + +### Tool Limitations + +Automated tools catch ~30-40% of issues. Manual testing required for: +- Alt text quality (not just presence) +- Focus order logic +- Cognitive accessibility +- Actual screen reader experience + +## Audit Report Structure + +```markdown +# Accessibility Audit Report + +**Site/Application**: [Name] +**Date**: [Date] +**Standard**: WCAG 2.1 Level AA +**Auditor**: [Name] + +## Executive Summary +[Overall findings, critical issues count, pass rate] + +## Critical Issues (Must Fix) +### Issue 1: [Description] +- **WCAG Criterion**: [Number and name] +- **Location**: [URL/component] +- **Impact**: [User groups affected] +- **Recommendation**: [How to fix] + +## Major Issues (Should Fix) +[Same format] + +## Minor Issues (Consider Fixing) +[Same format] + +## Passed Criteria +[List of criteria that passed] + +## Testing Methodology +[Tools used, manual tests performed] +``` + +## Quick Fixes Reference + +| Issue | Quick Fix | +|-------|-----------| +| Missing alt text | Add descriptive `alt` attribute | +| Low contrast | Increase color difference (use checker) | +| Missing form labels | Add `