CLAUDE.md

1# agent-skills
2 
3This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.
4 
5> **Scope:** This file configures agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself, not other projects. Don't copy it into another project or a global agent configuration; the reusable assets are the skills in `skills/`.
6 
7## Project Structure
8 
9```
10skills/       → Core skills (SKILL.md per directory)
11agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
12hooks/        → Session lifecycle hooks
13.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
14references/   → Supplementary checklists (testing, performance, security, accessibility, observability)
15evals/        → Skill eval cases + framework (see evals/README.md)
16docs/         → Setup guides for different tools
17```
18 
19## Skills by Phase
20 
21**Define:** interview-me, idea-refine, spec-driven-development
22**Plan:** planning-and-task-breakdown
23**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
24**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
25**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
26**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
27 
28## Conventions
29 
30- Every skill lives in `skills/<name>/SKILL.md`
31- YAML frontmatter with `name` and `description` fields
32- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
33- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
34- Shared references are in the root `references/` directory; the emerging convention for self-contained, distributable skills keeps a skill's own references inside `skills/<name>/references/`
35- Supporting files only created when content exceeds 100 lines
36 
37## Contributing
38 
39Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it.
40 
41## Commands
42 
43- `npm test` — Not applicable (this is a documentation project)
44- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
45- Evals: `node scripts/run-evals.js` — trigger/routing evals for every skill (CI); `--behavioral <skill>` for graded runs
46 
47## Pull Requests
48 
49PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here.
50 
51- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR.
52- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work.
53 
54## Boundaries
55 
56- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory
57- Always: Follow the skill-anatomy.md format for new skills
58- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR
59- Never: Add skills that are vague advice instead of actionable processes
60- Never: Duplicate content between skills — reference other skills instead
61