Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Write skills the way $analyze, $plan, $implement, $code-review, and $verify are written.
Target
- One job. Imperative. Every line changes behavior.
- Body under ~40 lines unless the job is genuinely multi-branch.
- Description 50–300 chars: capability first, then
Use when+ trigger words. - No README, changelog, or theory. No restating model defaults.
- References only for platform or schema detail the body cannot hold. Name the file and when to open it.
- User-only workflows:
disable-model-invocation: true.
Write
- Confirm 2–3 trigger prompts with the user.
- Pick the platform. Default from the path:
.claude→ Claude,.agents→ Codex,.cursor→ Cursor. Ask if unclear. - Write frontmatter, then the body: inspect → act → return → stop.
- Run
bun ~/.agents/skills/skill-manager/scripts/inspect-description.tson the skill root.
Personal skills live in ~/.agents/skills/<name>/. Platform layout and frontmatter: claude-code.md, codex.md, cursor.md. Description rules: description-recommandation.md.
Audit
For each line: would removing it change behavior? Delete no-ops, duplicates, and stale rules. State the positive target; keep prohibitions only as hard guardrails.
Online research: $find-docs for current technical docs; $exa-search for broader web research.
After creating or renaming a personal skill icon, run bun ~/.agents/scripts/sync-codex-profile-icons.ts --install. Compat: ~/.claude/skills and ~/.codex/skills symlink to ~/.agents/skills. Do not symlink ~/.cursor/skills.
