agent-skills

What you will run into

Your AI writes code fast, but often "just starts writing": no spec, no plan, no tests after the change. You want it to follow an engineering workflow like a senior engineer — think through the requirements first, split into small tasks, implement step by step, and only merge after tests pass. Agent Skills is an engineering-workflow skill package you install into your AI: 24 skills + 8 slash commands covering define → plan → build → test → review → ship.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

By default an AI only executes "the one sentence you give it" — it won't walk an engineering workflow on its own. Agent Skills gives the AI a "work manual": each skill is a SKILL.md directory (24 in total), and Agents like Claude Code auto-load the matching skill by task topic, or you can trigger the whole flow manually with slash commands. It doesn't modify the AI itself — it only puts files into the skill directory (~/.claude/skills/agent-skills/ or the project .claude/skills/). No CLI binary, no background process.

Step by step

Step 1: Install the skill package (manual copy preferred on mainland networks)

Why two methods: Method A is the officially recommended skills CLI (npx -y skills add ...), which supports 70+ agents and puts things in the right place automatically; but it clones from GitHub and often stalls on mainland networks. Method B downloads the tarball from codeload directly — verified reachable in this marketplace, plain directory copy, no Node needed. Note the two methods produce different on-disk layouts: Method A (isolated-verified 2026-08-30) writes the 24 skills flat into ~/.claude/skills/<skill-name>/ with no intermediate layer; Method B copies into ~/.claude/skills/agent-skills/<skill-name>/ with the intermediate layer. Claude Code reads both layouts, but counting and uninstall commands must match the install method. Method B (stable on mainland, verified in this marketplace):

curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills

Expected output: no errors; 24 skill directories appear under ~/.claude/skills/agent-skills/ After install, confirm (pick the command that matches your install method):

# Method A (flat): 24 skill dirs directly under ~/.claude/skills/ when installed alone
ls ~/.claude/skills | wc -l
# Method B (intermediate layer):
ls ~/.claude/skills/agent-skills | wc -l

Expected output: 24 Stuck? How to recover:

• codeload download failed → retry on another network (campus net/proxy switch); or use Method A skills CLI (npx -y skills add addyosmani/agent-skills --yes --global);
• skills not active → confirm they were copied to the skill directory the Agent actually reads (Claude Code: ~/.claude/skills/; other Agents have their own conventions).

Step 2: Trigger the workflow with slash commands

Why slash commands: they are the lifecycle entry points — /spec requirements → spec (Spec before code), /plan spec → atomic tasks, /build incremental implementation (/build auto plans + implements in one shot), /test tests as evidence, /review review before merge, /ship ship.

/spec    # 需求→规格（Spec before code）
/plan    # 规格→原子任务
/build   # 增量实现（/build auto 一键规划+实现）
/test    # 测试即证据
/review  # 合并前审查
/ship    # 上线

Expected output: corresponding workflow activated (related skills auto-loaded) After install, confirm:

• the slash command invokes the corresponding workflow (skill hints appear in the Agent context).

Stuck? How to recover:

• command not found → confirm the skill directory is in place (Step 1); Claude Code needs a session restart for the skill directory to take effect.

Step 3: Skills auto-activate (no manual command needed)

Why: designing an API auto-activates api-and-interface-design; changing UI activates frontend-ui-engineering, etc. This is the "auto-assemble by task" mechanism — skills don't depend on manual triggers.

# 设计 API 时自动激活 api-and-interface-design；改 UI 时激活 frontend-ui-engineering 等

Expected output: the agent context auto-injects the corresponding skill After install, confirm:

• skill references appear in relevant task hints.

Stuck? How to recover:

• not auto-activated → check whether the skill directory naming and SKILL.md format match the Agent's conventions (each Agent differs slightly).

How to confirm it works

1. Skill count is 24: Method A (flat) uses ls ~/.claude/skills | wc -l (when installed alone), Method B (intermediate layer) uses ls ~/.claude/skills/agent-skills | wc -l;
2. Open a fresh Claude Code session and type /spec — the AI responds with the spec workflow instead of writing code directly;
3. Skill references appear in relevant task hints (auto-activation works).

Other environments

• Other Agents (Cursor/Codex etc.): the skills CLI supports 70+ agents; Method A installs to the right place automatically; manual copy requires checking each agent's skill directory conventions.
• Node environment: Method B needs no Node; Method A needs Node >= 18.
• Project-only install: change the copy target from ~/.claude/skills/ to the project's .claude/skills/.
• Co-exist with superpowers / skilldock: skill directory write surface, no overlap with CLI tools; superpowers and agent-skills use different directory names and don't overwrite each other — both live under ~/.claude/skills/; skilldock may conflict (inferred, not tested).
• To remove: uninstall per install method, see the "Uninstall & cleanup" section — Method B deletes the directory, Method A must go through npx -y skills remove (deleting the directory alone leaves the CLI registration behind).

Daily usage

Startup and entry

No startup needed; skills are auto-loaded by the Agent by task topic. Manual entry points are the slash commands (Step 2) and the skill directory itself.

Common operations

Operation 1: Confirm the skill count (pick the command that matches your install method)

# Method A (flat)
ls ~/.claude/skills | wc -l
# Method B (intermediate layer)
ls ~/.claude/skills/agent-skills | wc -l

Expected output: 24 (when installed alone) Operation 2: Trigger a workflow with slash commands

/spec    # 需求→规格（Spec before code）
/plan    # 规格→原子任务
/build   # 增量实现（/build auto 一键规划+实现）
/test    # 测试即证据
/review  # 合并前审查
/ship    # 上线

Expected output: corresponding workflow activated (related skills auto-loaded) Operation 3: Update to the latest version (re-download and overwrite)

curl -sL https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz
cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills

Expected output: no errors; skill directory refreshed (24 skill directories)

Data and directories

• Skill directory: ~/.claude/skills/agent-skills/ (or project .claude/skills/); no config files, no background process.

Uninstall & cleanup

note: pure directory copy — deleting the skill directory is zero-residue; if installed via the skills CLI, remove through it as well

# rm -rf ~/.claude/skills/agent-skills .claude/skills/agent-skills
# npx -y skills remove addyosmani/agent-skills   (if installed via the skills CLI)
# test ! -d ~/.claude/skills/agent-skills && echo "agent-skills removed: OK"

Expected output: agent-skills removed: OK Manual checklist (other harnesses):

• project-level .claude/skills/agent-skills if installed there
• other Agents' skill directories if you copied skills manually

Dependency warnings

• Version: [0.6.7, 0.6.7] locked (collection structure confirmed version).
• Environment: Method A needs Node >= 18 (skills CLI); Method B has no runtime dependency (plain directory copy).
• Network: GitHub clone is slow (verified), codeload tarball is reachable (verified).
• Write surface: Method B ~/.claude/skills/agent-skills/, Method A flat ~/.claude/skills/<skill-name>/ (both share the surface with superpowers — plan the directory layout when installing multiple skill packages).

FAQ

• Q: Installed but not working? A: confirm the skill directory is in place (ls counts 24); Claude Code needs a session restart; other Agents follow their own skill directory conventions.
• Q: Method A or Method B? A: A is officially recommended (skills CLI, 70+ agent compatible); when GitHub is slow on mainland networks, B (codeload tarball, structure-confirmed in this environment) is more stable.
• Q: Will it overwrite superpowers if installed together? A: different directory names (agent-skills vs superpowers), no overwrite; both coexist under ~/.claude/skills/.
• Q: Why do Method A and Method B produce different layouts? A: the official skills CLI writes flat (~/.claude/skills/<skill-name>/), manual copy keeps the intermediate layer (~/.claude/skills/agent-skills/) — isolated-verified 2026-08-30; Claude Code reads both, count/uninstall per your method.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.