Claude Skill Builder

Claude Code Skill Builder

Build or revise skills as compact, task-specific operating guides. Keep the entrypoint small, put detailed material in one-level references/, and validate that generated agent targets preserve the intended behavior.

First Choice

In this repository, the canonical source is templates/.claude/skills/<skill-id>/skill.md.

Do not maintain separate hand-written Codex or Cursor copies. Codex SKILL.md files and Cursor .mdc rules are generated by src/utils/copy.js.

Workflow

1. Clarify the skill boundary:

   • What task should the agent become better at?
   • When should the skill trigger?
   • Which tools or bundled files are genuinely needed?
   • Is this a single workflow, or should it be several smaller skills?

2. Choose the folder and name:

   • Use lowercase kebab-case, max 63 characters.
   • Make the frontmatter name match the folder basename.
   • Prefer one top-level skill for a coherent domain and nested skills only when they are independently triggerable.

3. Write frontmatter:

   • name: exact folder basename.
   • description: include both what the skill does and when to use it. This is the trigger surface, so include natural user phrases and important domain terms.
   • allowed-tools: only for Claude Code source skills that need it.
   • model: optional; use an alias or current model ID only after checking current Claude Code model docs.

4. Keep the entrypoint lean:

   • State the purpose and fast workflow.
   • Include only essential decision rules and safety checks.
   • Link to references/<topic>.md for long examples, API details, or variant-specific guidance.
   • Add scripts only for repeated deterministic operations.
   • Avoid README, install guides, changelogs, and process notes inside the skill payload.

5. Make generated targets safe:

   • Do not rely on .claude/skills/... paths inside reusable instructions.
   • Refer to local skill resources with references/... from the skill root.
   • Avoid Claude-only runtime terms when the output will also install to Codex or Cursor.
   • Keep instructions agent-neutral unless a target-specific behavior is required.

6. Validate:

   • Run the skill-quality tests for this repo after changing templates.
   • For install behavior, run the real CLI into a temp directory for Codex and Cursor, not only helper-level tests.

File Shape

Simple skill:

skill-id/
├── skill.md
└── skill.json

Skill with detailed support:

skill-id/
├── skill.md
├── skill.json
├── references/
│   └── full-guide.md
├── scripts/
│   └── helper.js
└── assets/
    └── template.txt

Frontmatter Pattern

---
name: skill-id
description: What the skill helps with, when to use it, and important trigger phrases the user is likely to say.
allowed-tools: Read, Grep, Glob
model: sonnet
---

# Skill Title

One or two sentences explaining the operating mode.

## Fast Workflow

1. Inspect the target context.
2. Choose the relevant branch of the workflow.
3. Make the smallest useful change or answer.
4. Verify with the repo's real commands or artifacts.

## References

Read `references/full-guide.md` only when the task needs the longer details.

Quality Bar

• The skill teaches domain-specific procedure, not generic "be helpful" advice.
• The trigger description is clear enough to select the skill without reading the body.
• Examples use stable placeholders or current-source checks instead of stale dates, package versions, doc counts, or model IDs.
• References have a table of contents when long.
• Scripts are executable, deterministic, and easier to run than to retype.
• The installed Codex/Cursor output does not mention source-only paths that users will not have.

Repository Validation

npm test
npm run lint
cd site && npm run typecheck
cd site && npm run lint

Real install checks:

tmpdir="$(mktemp -d)"
node bin/cli.js init "$tmpdir" --yes --agent codex --profile all
node bin/cli.js init "$tmpdir" --yes --agent cursor --profile all --force
find "$tmpdir/.codex/skills" -maxdepth 2 -name 'SKILL.md' | sort
find "$tmpdir/.cursor/rules" -maxdepth 2 -name '*.mdc' | sort