addyosmani__agent-skills/docs/getting-started.md

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.

Want a worked example before setting up your own project? The interactive tutorials walk through a greenfield build, a brownfield feature, and a safe automation loop with copyable prompts for Claude Code, Codex, or any other agent.

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 when needed

If your agent does not route skills natively, start with the using-agent-skills skill loaded. It contains a flowchart that maps task types to the appropriate skill.

If your host already discovers and activates skills from their descriptions, do not also paste using-agent-skills into an always-on system prompt or rules file. That creates two routers for the same task. Install the individual skills and let the host activate them on demand instead.

Existing projects need no migration

Install the pack from the existing project's root using the normal setup path for your agent, then keep working in that project. Skills activate for matching tasks; they do not require a new repository layout or a one-time conversion of existing code.

Do not copy this repository's root AGENTS.md or CLAUDE.md into the project. Those files configure contributors to agent-skills itself. Add only the skills and any project-specific instructions your agent normally reads. For a gradual rollout in an established codebase, follow the Adoption Guide.

Recommended Setup

Rolling out to a real project? The Adoption Guide covers two end-to-end paths: the full lifecycle from day one for a greenfield project, and an incremental, verification-first rollout for an established codebase. The setup below is the quick version.

Minimal (Start here)

Load three essential skills into your rules file:

1. spec-driven-development — For defining what to build
2. test-driven-development — For proving it works
3. 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 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
web-performance-auditor.md	Core Web Vitals & performance audit (via /webperf)

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
/constraints	constraint-driven-development
/plan	planning-and-task-breakdown
/build	incremental-implementation + test-driven-development
/build auto	planning-and-task-breakdown → incremental-implementation + test-driven-development (whole plan, one approval)
/test	test-driven-development
/review	code-review-and-quality
/code-simplify	code-simplification
/ship	shipping-and-launch
/webperf	web-performance-auditor (specialist agent, web apps only)

Note: When installed as a Claude Code plugin you may see a warning like "Default commands/ folder is ignored because the manifest sets 'commands'". This is expected. The root commands/ directory belongs to the Antigravity CLI and is intentionally separate from .claude/commands/. All Claude Code slash commands load correctly from .claude/commands/; the warning is cosmetic.

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
definition-of-done.md	all skills / every change
observability-checklist.md	observability-and-instrumentation
orchestration-patterns.md	doubt-driven-development

Load a reference when you need detailed patterns beyond what the skill covers.

If you install one skill with npx skills add ... --skill <name>, only the selected skills/<name>/ directory is copied. The skill still works, but paths to supplementary checklists in the repo-level references/ directory are unavailable. Use a whole-repo integration, clone the repository, or copy the needed checklist into a references/ directory inside the installed skill. This portability gap is tracked in addyosmani/agent-skills#361.

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.

Working across sessions

The same artifacts are the handoff between sessions. For a small task, run the whole lifecycle in one session. For anything non-trivial, a fresh session per phase (spec → plan → build → review) keeps context focused — what carries the work forward is the approved files, not the conversation:

• the spec — SPEC.md, or wherever your spec actually lives
• tasks/plan.md and tasks/todo.md — or the external tracker the plan identifies, if you use one

Before switching, make sure those files reflect the decisions that still apply, the scope you approved, the questions still open, the next task, and the current verification state (which tests ran, against what).

In the new session, read the actual files and look at git status before doing anything. Don't assume approvals you can't see in the artifacts. Treat a recorded "tests pass" as a claim about a specific baseline: re-run the checks it covers if the code has moved since, if it doesn't say what was run against what, or if you're about to touch the area it covered. If the baseline still holds, take it and get on with the next task — the point is a check proportional to what changed, not a full suite at every handoff.

Task-boundary restarts and Ralph loops

/build auto can run the whole approved plan in one session. It does not require or perform a fresh process per task. Its per-task status updates, verification results, and commits make each completed task a restartable boundary, so a capable external harness may exit and resume there without depending on chat history.

A shell-level "Ralph loop" is harness behavior, not a separate skill workflow. If you use one, restart only after the current task has reached a recorded boundary; on re-entry, read the durable artifacts and repository state before selecting the next pending task. A process exit is not evidence that a task passed, and a restart must not bypass an approval gate. See the context-engineering skill's Restartable Session Boundaries section for the handoff checklist.

This doesn't need the /spec and /plan wrappers — plain requests work in any agent, including a npx skills add install that only has the skills:

Read SPEC.md, then break it into small verifiable tasks with acceptance criteria and dependency order. Save them to tasks/plan.md and tasks/todo.md. No product code yet — show me the plan first.

Read SPEC.md, tasks/plan.md and tasks/todo.md, then check where things actually stand — git status, plus re-running whatever checks the recorded verification state no longer covers. Tell me the next unchecked task and anything still open, then stop: I'll confirm the scope before you start it. If the plan looks incomplete, say what's missing rather than rewriting it.

Tips

1. Start with spec-driven-development for any non-trivial work
2. Always load test-driven-development when writing code
3. Don't skip verification steps — they're the whole point
4. Load skills selectively — more context isn't always better
5. Use the agents for review — different perspectives catch different issues