Skip to content

Add a skill

Skills live flat under skills/<name>/SKILL.md. No category subdirectories. Every skill is shared by Claude Code and Codex; read the compatibility contract before editing the frontmatter or instruction body.

1. Scaffold

Terminal window
./scripts/new-skill.sh my-new-skill

This creates:

skills/my-new-skill/
├── SKILL.md          # template
└── references/       # deeper content (one level only)

2. Write the SKILL.md

---
name: my-new-skill
description: >-
  What this skill does. Include 3–5 trigger phrases users would say.
allowed-tools: Read Grep Glob
disallowed-tools: WebFetch WebSearch
---


# my-new-skill


## When to use
- Specific scenario 1
- Specific scenario 2


## When NOT to use
- Wrong scenario (redirect to correct skill)


## Key principles
- Domain-specific principle 1
- Domain-specific principle 2


## Workflow


### Step 1: Name
Instructions...


### Step 2: Name
Instructions...


## References
- See [reference-name](references/file.md) for details

3. Quality checklist

  • SKILL.md under 500 lines
  • Name is kebab-case, max 64 chars
  • Name describes a developer workflow, never a project or brand — query-chain, not blockfrost (see DESIGN.md Decision 2; CI fails brand-named skills)
  • If the skill teaches integrating with a specific project, that project is a registered source — spec-level detail lives in docs/sources/, references/ holds behavioral guidance
  • name: matches directory name
  • Description includes trigger phrases
  • Has “When to use”, “When NOT to use”, “Key principles”, “Workflow” sections
  • No MCP dependency (no search_docs references)
  • Body describes capabilities without requiring Claude or Codex tool names
  • Bundled-doc paths resolve relative to SKILL.md, with no host-specific environment variables
  • Required safety behavior appears in the body, not only in Claude’s allowed-tools or disallowed-tools metadata
  • Deep content in references/, one level only — no nested subdirectories
  • No mention of specific deployed dApps; teach categories generically
  • No mention of grants, treasuries, or governance proposals — the skill must read as a neutral community contribution

4. Validate and submit

Terminal window
python3 scripts/validate.py
python3 scripts/check-pr-policy.py  # PR policy checks (vs origin/main)

Open a PR. CI runs validation and the PR policy checks (mechanical vetting + an advisory AI scope review comment).

Quality standards

  • Behavioural guidance over reference dumps. Tell the agent what to do and when — link to upstream docs for how.
  • Explain WHY, not just WHAT. Trade-offs, decision criteria, common mistakes.
  • Prescriptiveness scales with risk. Security skills should be strict. Exploratory skills can be flexible.
  • No hardcoded or host-variable paths. Resolve repository content relative to the active SKILL.md.