skill-manager

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: skill-manager
description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, prompts, frontmatter, references, scripts, discovery, and predictable skill design.
---

# Skill Manager

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:

- Claude Code → see [references/claude-code.md](references/claude-code.md)
- Codex      → see [references/codex.md](references/codex.md)
- Cursor     → see [references/cursor.md](references/cursor.md)
- Description quality → see [references/description-recommandation.md](references/description-recommandation.md)
- Skill-writing vocabulary → see [references/skill-writing-glossary.md](references/skill-writing-glossary.md)

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/`.

## Core principles (all platforms)

### Optimize for predictability

A skill should make the agent follow the same process on repeated runs, even when the outputs differ. Treat predictability as the root quality; token cost and maintainability improve when the process is explicit and lean.

### Concise is key

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?

### Match freedom to fragility

- **High freedom** (prose instructions): multiple valid approaches, decisions depend on context.
- **Medium freedom** (pseudocode, scripts with parameters): preferred pattern exists, some variation OK.
- **Low freedom** (specific scripts, few parameters): fragile, error-prone, must run a fixed sequence.

### Progressive disclosure

Three loading levels:

1. **Metadata** (name + description): always in context. Keep tight.
2. **SKILL.md body**: loaded when the skill triggers. Aim under ~500 lines.
3. **References**: loaded on demand. Move variant-specific detail, schemas, and long examples here.

Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.

### Design the information hierarchy

Put ordered actions in steps and definitions or rules in reference sections. End important steps with a checkable completion criterion; vague criteria invite premature completion. Inline what every execution branch needs and move branch-specific material behind a context pointer whose wording says when to load it.

Split a skill only when the split earns its cost:

- **By invocation:** a distinct leading word must trigger the new skill independently.
- **By sequence:** hiding later steps prevents the agent from rushing the current step.

Every model-invoked skill spends context load through its description. Every user-only skill spends human cognitive load because the user must remember it. When user-only skills become hard to remember, add one router inst