Getting Started with agent-skills
agent-skills works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
How Skills Work
Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria.**Skills are not reference docs.** They're step-by-step processes the agent follows.
Quick Start (Any Agent)
1. Clone the repository
git clone https://github.com/addyosmani/agent-skills.git
2. Choose a skill
Browse the `skills/` directory. Each subdirectory contains a `SKILL.md` with:
- When to use — triggers that indicate this skill applies
- Process — step-by-step workflow
- Verification — how to confirm the work is done
- Common rationalizations — excuses the agent might use to skip steps
- Red flags — signs the skill is being violated
3. Load the skill into your agent
Copy the relevant `SKILL.md` content into your agent's system prompt, rules file, or conversation. The most common approaches:**System prompt:** Paste the skill content at the start of the session.**Rules file:** Add skill content to your project's rules file (CLAUDE.md,.cursorrules, etc.).**Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change."
4. Use the meta-skill for discovery
Start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill.
Recommended Setup
Minimal (Start here)
Load three essential skills into your rules file:
- spec-driven-development — For defining what to build
- test-driven-development — For proving it works
- code-review-and-quality — For verifying quality before merge
These three cover the most critical quality gaps in AI-assisted development.
Full Lifecycle
For comprehensive coverage, load skills by phase:
Starting a project: spec-driven-development → planning-and-task-breakdown
During development: incremental-implementation + test-driven-development
Before merge: code-review-and-quality + security-and-hardening
Before deploy: shipping-and-launch
Context-Aware Loading
Don't load all skills at once — it wastes context. Load skills relevant to the current task:
- Working on UI? Load
frontend-ui-engineering - Debugging? Load
debugging-and-error-recovery - Setting up CI? Load
ci-cd-and-automation
Skill Anatomy
Every skill follows the same structure:
YAML frontmatter (name, description)
├── Overview — What this skill does
├── When to Use — Triggers and conditions
├── Core Process — Step-by-step workflow
├── Examples — Code samples and patterns
├── Common Rationalizations — Excuses and rebuttals
├── Red Flags — Signs the skill is being violated
└── Verification — Exit criteria checklist
See [skill-anatomy.md](https://github.com/addyosmani/agent-skills/blob/main/docs/skill-anatomy.md) for the full specification.
Using Agents
The `agents/` directory contains pre-configured agent personas:
| Agent | Purpose |
|---|
code-reviewer.md | Five-axis code review |
test-engineer.md | Test strategy and writing |
security-auditor.md | Vulnerability detection |
Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
Using Commands
The `.claude/commands/` directory contains slash commands for Claude Code:
| Command | Skill Invoked |
|---|
/spec | spec-driven-development |
/plan | planning-and-task-breakdown |
/build | incremental-implementation + test-driven-development |
/test | test-driven-development |
/review | code-review-and-quality |
/ship | shipping-and-launch |
Using References
The `references/` directory contains supplementary checklists:
| Reference | Use With |
|---|
testing-patterns.md | test-driven-development |
performance-checklist.md | performance-optimization |
security-checklist.md | security-and-hardening |
accessibility-checklist.md | frontend-ui-engineering |
Load a reference when you need detailed patterns beyond what the skill covers.
Spec and task artifacts
The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress:
- Keep them in version control during development so the human and the agent have a shared source of truth.
- Update them when scope or decisions change.
- If your repo doesn’t want these files long‑term, delete them before merge or add the folder to
.gitignore — the workflow doesn’t require them to be permanent.
Tips
- Start with spec-driven-development for any non-trivial work
- Always load test-driven-development when writing code
- Don't skip verification steps — they're the whole point
- Load skills selectively — more context isn't always better
- Use the agents for review — different perspectives catch different issues