// Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, skill prompts, frontmatter, references, scripts, and discovery rules.
| name | skill-manager |
| description | Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, skill prompts, frontmatter, references, scripts, and discovery rules. |
Authoring guide for skills/rules across three agent platforms. All three share the same idea: a small markdown file with frontmatter, optional references, optional scripts. The discovery rules and frontmatter fields differ.
| Platform | File | Frontmatter fields | Optional config |
|---|---|---|---|
| Claude Code | <scope>/skills/<name>/SKILL.md | name, description, plus invocation/execution fields | - |
| Codex | <scope>/.agents/skills/<name>/SKILL.md | name, description | agents/openai.yaml |
| Cursor | .cursor/rules/<name>.md or .mdc | description, globs, alwaysApply | AGENTS.md (no frontmatter) |
Pick the platform first, then read the matching reference file:
If unsure which the user wants, ask. Default to Claude Code when working under ~/.claude/ or .claude/, Codex when under ~/.agents/ or .agents/, Cursor when under .cursor/.
The context window is shared with the system prompt, conversation, other skills' metadata, and the user request. Only add context the agent doesn't already have. Challenge each line: does it justify its tokens?
Three loading levels:
Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
skill-name/
├── SKILL.md # required: frontmatter + instructions
├── references/ # optional: docs loaded on demand
├── scripts/ # optional: deterministic code
└── assets/ # optional: templates/icons used in output
Do NOT add README, CHANGELOG, INSTALLATION_GUIDE, etc. Only files the agent needs at runtime.
The description field is the single most important line in the file - it's what the model uses to decide to load the skill. This is a hard rule: descriptions must be between 50 and 300 characters.
Write it as:
Bad: "Helper for skills."
Good: "Create and edit skills/rules across Claude Code, OpenAI Codex, and Cursor. Use when the user asks to 'create a skill'..."
To validate skill descriptions, frontmatter fields, agents/openai.yaml, and skill directory shape, run:
bun scripts/inspect-description.ts
By default, this checks ~/.agents/skills only and follows symlinked skill directories inside that root. Pass one or more roots to inspect a different set. Passing a .cursor/rules directory validates Cursor rule frontmatter too:
bun scripts/inspect-description.ts .agents/skills
For researched guidance and examples, see references/description-recommandation.md.
See the per-platform reference files. Quick reminders:
~/.claude/skills/ (personal) or .claude/skills/ (project). Higher scope wins on name collision..agents/skills/ walks up from CWD to repo root, then ~/.agents/skills/, then /etc/codex/skills, then system bundled..cursor/rules/ (project, version-controlled) or AGENTS.md files in project subdirectories.A brief description of what this skill does
Set up per-worktree environments for Claude Code, Cursor, or Codex. Use for worktree-ready repos, IDE environment config, worktree-up/down scripts, or dev.sh wiring.
Create and maintain agent rules in AGENTS.md and .agents/rules/. Use for project rules, conventions, constraints, rule indexes, or requests to add or optimize agent rules.
Expert guidance for creating, building, and using Claude Code agents and the Task tool. Use when working with agents, setting up agent configurations, understanding how agents work, or using the Task tool to launch specialized agents.