# jutsu.sh

> A deep technical reference on building, evaluating, and shipping agent skills across Claude Code, Codex CLI, and Gemini CLI.

jutsu.sh covers the open agent skills standard (SKILL.md format), platform-specific implementations, trigger optimization, eval-driven development, and advanced patterns for teams building with AI agents.

Author: Anshumani Ruddra
- LinkedIn: https://www.linkedin.com/in/anshumani/
- Twitter/X: https://x.com/baboonzero
- Maven masterclass: https://maven.com/anshumani/agent-skills

## Sections

- [Before You Start](https://jutsu.sh/#s0): Install comparison table for Claude Code, Codex CLI, and Gemini CLI. Skills directory setup.
- [Why Skills Exist](https://jutsu.sh/#s1): The context window problem. Why agents forget. Three-tier loading model (always-on, on-demand, injected). Why skills compound over time.
- [The Open Standard](https://jutsu.sh/#s2): SKILL.md format specification. Frontmatter fields (name, description, triggers, version). Directory structure. Validation commands.
- [Mental Model](https://jutsu.sh/#s3): Skills as persistent memory. Mechanism comparison: skills vs. system prompts vs. MCP tools. Recommended build order.
- [Platform Implementations](https://jutsu.sh/#s4): Claude Code (~/.claude/skills/), Codex CLI (~/.codex/skills/ + openai.yaml), Gemini CLI (~/.gemini/skills/ + AgentCard JSON). Platform comparison table.
- [Creating Effective Skills](https://jutsu.sh/#s5): Sourcing expertise. Writing the body. Scripts. Progressive disclosure. Production examples (csv-analyzer, TDD workflow, autoresearch-meta).
- [Skill Design Workflow](https://jutsu.sh/#s5-design): Five-phase workflow: source, write, test, eval, iterate.
- [Trigger Optimization](https://jutsu.sh/#s6): How agents match queries to skills. Description budget. Near-miss query testing. Trigger anti-patterns.
- [Eval-Driven Development](https://jutsu.sh/#s7): Designing test cases. evals.json structure. Assertion types. Aggregating results. The iteration loop. Karpathy autoresearch pattern.
- [Ecosystem and Protocols](https://jutsu.sh/#s8): skills.sh registry. MCP integration. Agent-to-agent (A2A) skill sharing.
- [Advanced Patterns](https://jutsu.sh/#s9): Skill composition. Team skill libraries. CI/CD for skills. Versioning strategies.
- [Quick Reference](https://jutsu.sh/#s10): Checklists, command reference, common gotchas.
- [References](https://jutsu.sh/#s11): Primary sources and further reading.

## Key Concepts

**SKILL.md format**: A markdown file with YAML frontmatter. Required fields: `name` (short identifier), `description` (what the skill does and when to use it - this is what the agent reads to decide whether to load the skill). Optional fields: `triggers` (example queries), `version`, `author`.

**Skills directory**: Platform-specific but conceptually identical. Place SKILL.md files in the agent's skills directory. The agent discovers and loads them automatically.

**Trigger optimization**: The `description` field is a budget of ~150 tokens. It must answer "would the agent load this skill for query X?" Write it as a retrieval document, not a marketing blurb.

**Eval-driven development**: Write test cases before writing the skill body. Each test case is a query + expected behavior assertion. Run evals after every edit. Iterate until pass rate is acceptable.

**Progressive disclosure**: Structure skill content from most-used to least-used. The agent reads top-to-bottom and stops when it has enough context. Put defaults and common cases first, edge cases last.