AI Agent Skills System

This documents everything we know about how skills work across Claude Code, Gemini CLI, Codex, and Cursor, learned from building and organizing this project's skills. This knowledge will inform Capsem's own skills system for guest AI agents.

Discovery

Claude Code

• Looks in .claude/skills/ (project) and ~/.claude/skills/ (global)
• Discovers <name>/SKILL.md -- one level of nesting only
• Nested directories (e.g., category/skill/SKILL.md) are NOT discovered
• Symlinks work -- we use .claude/skills -> ../skills to share with Gemini
• Live reload on file change, no restart needed

Gemini CLI

• Looks in .agents/skills/ or .gemini/skills/
• Same <name>/SKILL.md format as Claude Code
• We use .agents/skills -> ../skills and .gemini/skills -> ../skills symlinks

Codex and Cursor

• Project-local .codex/skills/ and .cursor/skills/ point to the shared skills/ directory so those clients consume the same project skills.
• bootstrap.sh creates .claude, .agents, .gemini, .codex, and .cursor skill symlinks non-destructively.

What does NOT work

• Nested categories: skills/dev/testing/SKILL.md is not found by either CLI
• Files named anything other than SKILL.md in a directory are not discovered as skills
• Files directly in the skills root (not in a subdirectory) are not discovered

No Escape-Hatch Skill Paths

Do not add alternate skill/bootstrap validation modes named fast, check, or dry-run behind separate flags. Forked verification paths are how projects lose the real contract. The shared skill rail must be fast, hermetic, and complete enough to run every time; if it is not, fix the rail instead of adding a bypass.

Bank of Iron Feature Tribute

Every feature owes a pure black-box ledger test. The test must exercise the public path end to end and account for the exact input and output: client-visible result, parsed event facts, security decision, detection/enforcement records, protocol rows, structured logs, counters, and route/UI JSON when those surfaces exist. No feature is done with a single-entry proof. What goes in must come out exactly, and every transformation must be accounted for.

Runtime Image Memory

When image-build work touches config/docker/image/ or guest/artifacts/, load the build-images skill. The VM runtime has no build hook: its package set is runtime_apt_packages in config/docker/image/build.toml, reserved for Capsem's own guest machinery. Tools a user or agent works with belong in an OCI image under images/. A runtime change is only real in a VM after just build-assets rebuilds it; boot a fresh VM and pay the Ironbank proof for the user-visible behavior.

config/skills is not a development skill location. Read config/README.md before adding any product skill payload, and keep repository development skills in top-level skills/.

SKILL.md format

---
name: skill-name
description: When to trigger and what it does. Be specific and pushy -- Claude undertriggers.
---

# Skill Title

Instructions the agent follows when triggered.

Frontmatter fields

• name (required) -- skill identifier, should match directory name
• description (required) -- this is the PRIMARY trigger mechanism. Claude sees name + description in its skill list and decides whether to load the full body. Everything about "when to use" goes here.
• user-invocable: true -- lets users invoke with /skill-name
• allowed-tools -- restrict which tools the skill can use
• context: fork -- run in a subagent

Description is everything for triggering

Claude undertriggers skills by default. Descriptions must be:

• Specific about WHAT the skill does
• Explicit about WHEN to use it (list concrete contexts, phrases, file types)
• Slightly pushy -- "Use this whenever X, even if Y" style

Bad: "Frontend development guide" Good: "Capsem frontend design system. Use when building UI components, styling views, working with the design system, choosing colors, or understanding the component library."

Progressive disclosure

Three loading tiers:

1. Metadata (~100 words) -- name + description, always in context for every conversation
2. SKILL.md body (<500 lines ideal) -- loaded when skill triggers
3. Bundled resources (unlimited) -- <skill>/references/, <skill>/scripts/, and <skill>/assets/, loaded on demand

This means: keep SKILL.md lean. Put detailed wire formats, API docs, and large references in references/ with clear pointers from the SKILL.md body.

Organization: prefix-based grouping

Flat directory structure with naming convention for categories:

skills/
  dev-testing/SKILL.md          dev category
  dev-debugging/SKILL.md        dev category
  build-images/SKILL.md         build category
  release-process/SKILL.md      release category
  meta-find-skills/SKILL.md     meta category

Categories we use: meta-*, dev-*, build-*, release-*, site-*, frontend-*.

Bundled resources pattern

skill-name/
  SKILL.md                      Main instructions (<500 lines)
  references/
    wire-format.md              Detailed protocol docs
    community-skill.md          Fetched from npx skills / GitHub
  skill-name/scripts/
    helper.sh                   Executable automation
  assets/
    template.html               Templates, icons

Reference from SKILL.md with a sentence naming the file, for example: Read references/<topic>.md for the full protocol details.

Community skills

The npx skills CLI (skills.sh) discovers community skills. To use one:

npx skills find <query>          # Search
# Then manually fetch and place:
curl -sL https://raw.githubusercontent.com/<owner>/<repo>/main/<path>/SKILL.md \
  -o skills/<name>/references/<topic>.md

We place community skills as references (not top-level SKILL.md) because:

• They're context for our skills, not standalone triggers
• Our SKILL.md provides the project-specific framing
• Community skills may have generic advice that conflicts with our conventions

Quality bar: prefer official sources (anthropics/, sveltejs/, google-gemini/) or 1K+ installs. Verify content before bundling.

Global skills

Skills in ~/.claude/skills/ are available across all projects. We install meta skills globally:

• meta-find-skills -- discover community skills
• meta-organize-skills -- skill conventions
• meta-skill-creation -- create/iterate skills

Lessons learned

1. Nested directories don't work for skill discovery. Use prefix naming instead.
2. Description quality drives triggering accuracy. Vague descriptions = skill never loads.
3. Wire format docs belong in references/, not in the main SKILL.md. Keep the body actionable.
4. Write references from source code, not from memory. API wire formats drift and memory gets stale.
5. One skill per concern. MCP and MITM proxy are separate skills even though both handle network traffic -- they have different trigger conditions.
6. Cross-reference between skills using "See dev-testing-vm for..." style pointers in the body.
7. Skills load on demand -- having 18 skills costs nothing when they're not triggered. Don't try to merge skills to save space.
8. Agent clients read the same format. SKILL.md with YAML frontmatter works for Claude Code, Gemini CLI, Codex, and Cursor. No duplication needed.
9. Treat local/CI parity as a tested contract. A Linux asset workflow once failed only in CI because the doctor required x86_64-linux-musl-gcc on an arm64 runner even though the native musl-gcc installed by musl-tools was the real build contract. The local Docker rail had tested package installation but not that exact doctor predicate. Whenever CI exposes a missing dependency or runner assumption, execute the same production entrypoint or shared predicate locally in Docker when possible, add a regression, and audit sibling workflows before retrying CI. Record any unavoidable platform boundary explicitly.

Guards encode a rule; they do not replace it

When a rule keeps being broken, the first move is a function that makes the break unrepresentable -- not a lint that scolds. Add the guard to stop regressions after the wrapper exists, and point it at the wrapper.

A guard must be precise before it is useful. Ours needed four iterations, each failing the same way: too coarse. It flagged prose for containing a retired term inside a current one; it flagged whole files for containing two shapes that never met; it flagged a variable named path in one function because another function had a parameter of that name. A guard with false positives teaches people to add exemptions, and the pressure is always to narrow its scope to fit the code rather than fix the code.

Before trusting a new guard: run it, read every hit, and confirm each is real. Then break the rule deliberately and confirm it fails. A guard that has never been red is a guard you have not tested.