melvynx/aiblueprint · GitHub
Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and skill discovery.
프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.
npx skills add melvynx/aiblueprint --skill skill-manager설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.
agents/openai.yamlinterface: display_name: "Skill Manager" short_description: "Create or edit Claude, Codex, and Cursor skills/rules" icon_small: "./assets/codex-icon.svg" icon_large: "./assets/codex-icon.svg" brand_color: "#48AAB0" default_prompt: "Use $skill-manager to help with this task." policy: allow_implicit_invocation: true
assets/codex-icon.svg<!-- @license lucide-static v1.24.0 - ISC --> <svg role="img" aria-label="skill-manager skill icon" class="lucide lucide-notebook-tabs" xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 24 24" fill="none" stroke="#F5F5F5" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" > <path d="M2 6h4" /> <path d="M2 10h4" /> <path d="M2 14h4" /> <path d="M2 18h4" /> <rect width="16" height="20" x="4" y="2" rx="2" /> <path d="M15 2v20" /> <path d="M15 7h5" /> <path d="M15 12h5" /> <path d="M15 17h5" /> </svg>
references/claude-code.md# Claude Code Skills
Official docs: https://code.claude.com/docs/llms.txt
## Layout
```
skill-name/
├── SKILL.md # required
├── references/ # loaded on demand
├── scripts/ # executable code
└── assets/ # templates, icons, fonts used in output
```
## Storage locations
| Location | Path | Applies to |
| :--------- | :--------------------------------------- | :--------------------- |
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects |
| Project | `.claude/skills/<name>/SKILL.md` | This project only |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin enabled |
| Enterprise | Managed settings | Whole org |
Precedence on name collision: enterprise > personal > project. Nested `.claude/skills/` under subdirectories is auto-discovered (monorepos).
## SKILL.md frontmatter
**Core**
- `name` (optional, defaults to directory name): lowercase, hyphens, max 64 chars.
- `description` (recommended): what it does + when to use. Front-load trigger keywords.
**Invocation control**
- `disable-model-invocation: true` - only the user can invoke. Use for side-effecting commands like `/deploy`.
- `user-invocable: false` - only Claude can invoke. Use for background knowledge.
- `argument-hint: "[issue-number]"` - shown in autocomplete.
**Execution control**
- `allowed-tools: [Read, Edit, Bash]` - tools usable without permission prompts.
- `model: claude-sonnet-4-6` - override active model.
- `context: fork` - run in a forked subagent context (no conversation history).
- `agent: Explore` - subagent type when `context: fork` is set.
- `hooks` - lifecycle hooks scoped to this skill.
**Substitutions in body**
- `$ARGUMENTS` - args passed when invoking.
- `${CLAUDE_SESSION_ID}` - current session ID.
**Dynamic context injection**: prefix a shell command with `!` and wrap in backticks; output replaces the placeholder before the body is sent to the model.
## Example: subagent-forked skill
```markdown
---
name: deep-research
description: Research a topic thoroughly. Use when the user asks to research, investigate, or deeply explore a topic that requires multiple file reads and web searches.
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with file references
```
## Bundled resources
- **`scripts/`**: deterministic code (Python, Bash, TS). Run without loading into context. Include only when the same code would be rewritten repeatedly.
- **`references/`**: docs loaded on demand. Schemas, API specs, long examples, domain glossaries. Keep one level deep.
- **`assets/`**: files used in output (templates, fonts, boilerplate). Not loaded into context.
## Common mistakes
- Description that labels instead of triggers ("Helper for X" → "Use when the user asks to X...").
- SKILL.md > 500 lines without splitting into references.
- README/CHANGELOG files next to SKILL.md.
- Duplicating the same content in SKILL.md and references.
references/codex.md# OpenAI Codex Skills
Official docs: https://developers.openai.com/codex/skills
Examples: https://github.com/openai/skills
## Layout
```
skill-name/
├── SKILL.md # required
├── agents/
│ └── openai.yaml # optional: UI metadata, MCP deps, default prompt
├── assets/ # icons referenced by openai.yaml, output templates
├── references/ # loaded on demand
└── scripts/ # executable code
```
## Storage locations (scan order)
| Scope | Path | Use |
| :------- | :------------------------------ | :----------------------------------- |
| REPO | `$CWD/.agents/skills` | Skill scoped to working folder |
| REPO | `$CWD/../.agents/skills` | Shared across nested module |
| REPO | `$REPO_ROOT/.agents/skills` | Repo-wide for everyone |
| USER | `~/.agents/skills` | Personal, any repo |
| ADMIN | `/etc/codex/skills` | Machine/container-wide |
| SYSTEM | bundled with Codex | Built-ins |
Codex walks CWD up to repo root collecting `.agents/skills` at each level. Symlinks are followed. Same `name` in two scopes is NOT merged - both appear in the selector.
## SKILL.md (required, minimal)
```markdown
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Imperative instructions for Codex.
```
Only `name` and `description` are required. The description is what triggers implicit invocation - front-load the use case and trigger words. Codex caps the initial skill list at ~2% of context (or ~8000 chars); descriptions get shortened first, so the important phrases must come first.
## Invocation
- **Explicit**: user types `$skill-name` in CLI/IDE, or `/skills` to browse.
- **Implicit**: Codex picks the skill when the user's prompt matches the description.
To block implicit picking (e.g., for side-effecting skills), set `policy.allow_implicit_invocation: false` in `openai.yaml`. `$skill-name` still works.
---
# `agents/openai.yaml` - the optional UX layer
`openai.yaml` is product-specific config the **harness** reads, not the model. It controls how the skill appears in the Codex app/IDE (icon, name, color, blurb), how it can be invoked, and what MCP servers it needs to function. The skill still works without it - this layer makes it feel native.
## When to add it
- **Skip** for a personal, instruction-only skill in your own repo. SKILL.md alone is fine.
- **Add it** when you want the skill to look polished in the Codex app skill picker (real icon, brand color, friendly name).
- **Required** if the skill needs an MCP server (Figma, Notion, Linear, GitHub, etc.) to function - that's how Codex knows to connect.
- **Required** if you want to disable implicit invocation for safety.
## Full schema with constraints
```yaml
interface:
display_name: "Optional user-facing name"
short_description: "Optional user-facing description"
icon_small: "./assets/small-400px.png"
icon_large: "./assets/large-logo.svg"
brand_color: "#3B82F6"
default_prompt: "Use $skill-name to draft a concise weekly status update."
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "github"
description: "GitHub MCP server"
transport: "streamable_http"
url: "https://api.githubcopilot.com/mcp/"
```
**Top-level rules**
- Quote every string value. Leave keys unquoted.
- Paths in `icon_small` / `icon_large` are relative to the skill directory. Convention: put icons under `./assets/`.
### `interface` fields (UI metadata)
| Field | Purpose | Notes |
| :------------------ | :-------------------------------------------- | :----------------------------------------------------------------------------------- |
| `display_name` | Human-facing title in skill lists/chips | Keep short. Don't repeat the `name` slug. |
| `short_description` | One-line blurb for skill picker | **25-64 chars**. Skim-readable. |
| `icon_small` | Small icon path | Use `./assets/<file>`. PNG or SVG. Used in chips/lists. |
| `icon_large` | Large logo path | Used on the skill detail card. |
| `brand_color` | Hex color for UI accents | Format `"#RRGGBB"`. Picks badge / pill color. |
| `default_prompt` | Example prompt inserted when invoking | **Must mention the skill as `$skill-name`** (e.g., "Use `$weekly-status` to draft…") |
### `policy` field
- `allow_implicit_invocation` (default: `true`). Set to `false` for skills with side effects (deploy, post, write). Users can still trigger with `$skill-name`.
### `dependencies.tools` (MCP)
Only `type: "mcp"` is supported today. Each entry:
| Field | Required | Description |
| :------------ | :------- | :----------------------------------------------------------------------- |
| `type` | yes | Always `"mcp"` for now |
| `value` | yes | Server identifier. Must match `[mcp_servers.<value>]` in `config.toml` |
| `description` | yes | Human-readable purpose |
| `transport` | yes | Always `"streamable_http"` for remote MCP servers |
| `url` | yes | HTTPS endpoint of the MCP server |
---
## Wiring an MCP-backed skill end-to-end
Two files have to agree:
**1. Skill declares the dependency** (`<skill>/agents/openai.yaml`)
```yaml
dependencies:
tools:
- type: "mcp"
value: "figma"
description: "Figma MCP server for design-to-code"
transport: "streamable_http"
url: "https://mcp.figma.com/mcp"
```
**2. User configures the server** (`~/.codex/config.toml`)
```toml
rmcp_client = true # required feature flag for remote MCP
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
# optional:
# http_headers = { "X-Figma-Region" = "us" }
# startup_timeout_sec = 10
# tool_timeout_sec = 30
```
The token itself lives in the environment:
```bash
export FIGMA_OAUTH_TOKEN="…"
```
Restart Codex after editing `config.toml` or the env var.
**Real-world reference table**
| Skill | MCP `value` | URL | Env var |
| :----------------------------- | :---------- | :--------------------------- | :-------------------- |
| `figma` | `figma` | `https://mcp.figma.com/mcp` | `FIGMA_OAUTH_TOKEN` |
| `notion-knowledge-capture` | `notion` | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN` |
| `notion-meeting-intelligence` | `notion` | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN` |
| `notion-spec-to-implementation`| `notion` | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN` |
---
## Enable/disable a skill without deleting
`~/.codex/config.toml`:
```toml
[[skills.config]]
path = "/absolute/path/to/skill/SKILL.md"
enabled = false
```
Restart Codex after editing.
## Distribution
For sharing beyond one repo, bundle as a **plugin**. Plugins can hold one or more skills plus MCP server config and app mappings. `.agents/skills/` is for local authoring; plugins are for distribution. `$skill-installer <name>` pulls curated skills locally.
---
## Recipes
### Pure instruction-only skill (no UI polish, no MCP)
```
weekly-status/
└── SKILL.md
```
```markdown
---
name: weekly-status
description: Draft a concise weekly status update. Use when the user asks to "write my weekly status", "summarize the week", or "draft a standup update".
---
Draft a 4-bullet status:
1. Shipped this week (link PRs)
2. In progress with current blockers
3. Coming next week
4. Asks / decisions needed
Keep each bullet under 20 words. No emoji. No filler.
```
### Polished skill with branded UI
```
weekly-status/
├── SKILL.md
├── agents/openai.yaml
└── assets/
├── small-400px.png
└── large-logo.svg
```
```yaml
interface:
display_name: "Weekly Status"
short_description: "Draft a concise weekly status update"
icon_small: "./assets/small-400px.png"
icon_large: "./assets/large-logo.svg"
brand_color: "#7C3AED"
default_prompt: "Use $weekly-status to draft this week's update from my recent PRs."
```
### Side-effecting skill (block implicit)
```yaml
interface:
display_name: "Deploy Production"
short_description: "Ship the current branch to prod"
brand_color: "#DC2626"
default_prompt: "Use $deploy-prod to release the current branch."
policy:
allow_implicit_invocation: false # user must type $deploy-prod
```
### MCP-backed skill (Figma example)
```yaml
interface:
display_name: "Figma"
short_description: "Implement designs from Figma nodes"
icon_small: "./assets/figma-small.svg"
icon_large: "./assets/figma.png"
brand_color: "#F24E1E"
default_prompt: "Use $figma to implement the selected node."
dependencies:
tools:
- type: "mcp"
value: "figma"
description: "Figma design context"
transport: "streamable_http"
url: "https://mcp.figma.com/mcp"
```
Skill body then calls the MCP tools in a deterministic sequence (e.g., for Figma: `get_design_context` → `get_metadata` if truncated → `get_screenshot` for parity).
---
## Common mistakes
- **Description is a label, not a trigger.** "Figma helper" → "Use when the user asks to implement a Figma design, build UI from a Figma node, or convert a Figma URL to code."
- **Forgot to quote string values** in YAML. Unquoted hex colors / URLs blow up parsing.
- **`default_prompt` doesn't reference `$skill-name`**. Per the schema constraint, it must.
- **MCP `value` mismatch.** The string in `openai.yaml` must match the `[mcp_servers.<value>]` block in `config.toml` exactly.
- **Forgot `rmcp_client = true`** in `config.toml` - MCP connections silently fail.
- **Bearer token has quotes.** `bearer_token_env_var` resolves to the raw env value; if you wrap it in quotes when exporting, OAuth errors out.
- **Adding `openai.yaml` for a personal skill that nobody else sees.** It's overhead. Skip it.
- **Putting README/CHANGELOG/INSTALL files next to SKILL.md.** Codex doesn't read them, they're clutter.
## Best practices
- One job per skill. Split rather than bloat.
- Instructions over scripts unless determinism matters.
- Imperative steps with explicit inputs and outputs.
- Re-read the `description`: would it actually match the prompts you have in mind? Test against 3 real phrasings.
- Keep `short_description` skim-readable (25-64 chars).
- Pre-size icons before shipping: small ~400px, large ~1024px square. Match `brand_color` to the icon for cohesion.
references/cursor.md# Cursor Rules
Official docs: https://cursor.com/docs/rules.md
Cursor calls them "rules", not skills. Same idea: persistent instructions injected into the model context. Four kinds:
| Kind | Location | Notes |
| :------------ | :------------------------- | :--------------------------------- |
| Project Rules | `.cursor/rules/*.md(c)` | Version-controlled, scoped to repo |
| User Rules | Cursor Settings → Rules | Global, chat-only |
| Team Rules | Cursor dashboard | Team/Enterprise plans |
| AGENTS.md | project root + subdirs | Plain markdown, no frontmatter |
Precedence when merging: **Team Rules → Project Rules → User Rules**. Earlier source wins on conflict.
## Project rule file: `.cursor/rules/<name>.mdc`
Use `.mdc` when you need frontmatter, `.md` for content-only. Frontmatter has three fields:
| `alwaysApply` | `description` | `globs` | Behavior |
| :------------ | :------------ | :-------- | :------------------------------------------------------ |
| `true` | - | - | Always included. `description`/`globs` ignored. |
| `false` | - | provided | Auto-attached when a matching file is in context. |
| `false` | provided | omitted | Agent reads description, pulls in when relevant. |
| `false` | omitted | omitted | Manual only - included when `@`-mentioned in chat. |
### Four templates
**Always applied**
```md
---
alwaysApply: true
---
- All source files must include the company copyright header
- Never modify generated files in `dist/` or `build/`
```
**Auto-attached by file pattern**
```md
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports
- Co-locate styles in a CSS module next to the component
- Keep components under 200 lines
```
**Agent-selected by description**
```md
---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---
- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary
- Reference `@service-template.ts` for boilerplate
```
**Manual via @-mention**
```md
---
alwaysApply: false
---
- Every database migration must have `up` and `down`
- Never alter a column type in-place
@migration-template.sql
```
### Glob examples
| Pattern | Matches |
| :------------------------------- | :----------------------------------- |
| `*.ts` | `.ts` files at root |
| `**/*.ts` | `.ts` files anywhere |
| `src/**` | everything under `src/` |
| `src/**/*.tsx` | `.tsx` files anywhere under `src/` |
| `docs/**/*.md, docs/**/*.mdx` | comma-separate multiple patterns |
| `tailwind.config.*` | any extension |
### Referencing files
`@filename.ts` inside a rule attaches that file to the context when the rule fires. Use this to point at canonical templates instead of copying code.
## AGENTS.md (no frontmatter)
Plain markdown in project root or subdirectories. No fields, no globs - just instructions.
```markdown
# Project Instructions
## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
```
Nested support: `frontend/AGENTS.md` applies inside `frontend/`, combined with the root file. More specific wins.
## User Rules
Free-form global preferences set in Cursor Settings. Chat-only (not Inline Edit / Cmd-K).
## Best practices
- Keep rules under 500 lines; split into composable rules instead.
- Concrete examples beat vague guidance.
- Reference files with `@name.ts` rather than copying code (stays in sync).
- Skip style guides Cursor already knows. Add a rule when you see the same mistake twice.
- Check rules into git so the team benefits.
## Common mistakes
- Using `alwaysApply: true` for rules that only matter in one directory - use `globs` instead.
- Description that's a label, not a trigger ("Backend stuff" → "RPC service conventions and patterns for the backend").
- Copying entire style guides instead of using a linter.
- Manual rule (no globs, no description, `alwaysApply: false`) without telling the user it must be `@`-mentioned.
references/description-recommandation.md# Description Load this when writing or refining a `description` field. Official docs: Codex https://developers.openai.com/codex/skills · Claude https://docs.anthropic.com/en/docs/claude-code/skills · Cursor https://cursor.com/docs/skills ## Rules - 50–300 characters. - First clause useful alone; skill lists may truncate. - What it does + when to use it. Third person. No `I can` / `You can`. - No XML, tables, long examples, or body-level steps. - Trigger-first: nouns, verbs, file names, and commands the user would type. ## Shape ```yaml description: <Primary capability>. Use when <trigger phrases, files, commands, or task context>. ``` Good: `Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.` Good: `Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.` Bad: `Helps with skills.` / `I can help you write better skill descriptions.` / a catalog of every adjacent task. Then run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root.
references/skill-writing-glossary.md# Glossary - Building Great Skills
The domain model for predictable skills. Every term below is a lever for making an agent follow the same process on repeated runs. This is the disclosed vocabulary reference for [`skill-manager`](../SKILL.md).
The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
## Predictability
The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
_Avoid_: consistency, reliability, robustness, output-determinism
## Invocation
How a skill is reached — and the two loads you pay for the choice.
### Model-Invoked
A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
_Avoid_: ability, tool, capability
### User-Invoked
A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
_Avoid_: procedure, workflow, command
### Description
The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
_Avoid_: frontmatter, summary
### Context Pointer
A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
_Avoid_: link, reference, import
### Context Load
The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
_Avoid_: token cost, context bloat
### Cognitive Load
The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
_Avoid_: human index, burden, overhead
### Router Skill
A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
_Avoid_: dispatcher, menu, registry, index, router procedure
### Granularity
How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
_Avoid_: chunking, modularity
## Information Hierarchy
How a skill's content is arranged, and how far down the ladder each piece sits.
### Information Hierarchy
A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
- **Steps** — in-file, primary
- **Reference**, in-file — secondary
- **Reference**, disclosed — behind a **context pointer**
A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
_Avoid_: structure, organization, layout
### Steps
The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
_Avoid_: workflow, instructions, choreography
### Reference
Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
_Avoid_: supporting material, docs, background
### External Reference
**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
_Avoid_: doc, resource, knowledge base
### Progressive Disclosure
Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
_Avoid_: lazy loading, chunking
### Co-location
Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
_Avoid_: grouping, clustering, cohesion
### Sprawl
_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
_Avoid_: bloat, length, size, verbosity
## Steering
The levers that shape the agent's runtime behaviour toward **Predictability**.
### Branch
A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
_Avoid_: path, case, fork
### Leading Word
A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
_Avoid_: keyword, term, motif
### Completion Criterion
The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
_Avoid_: done condition, exit condition, stopping rule
### Legwork
The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
_Avoid_: scope, effort, diligence, coverage
### Post-Completion Steps
The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
_Avoid_: horizon, fog of war, lookahead
### Premature Completion
_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
_Avoid_: premature closure, the rush, rushing, shortcutting
### Negation
_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
_Avoid_: ironic rebound, don't-prompting, the pink elephant
## Pruning
Keeping a skill lean — each remedy paired with the failure it cures.
### Single Source of Truth
The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
_Avoid_: home, canonical location
### Duplication
_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
_Avoid_: repetition, redundancy
### Relevance
Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
_Avoid_: load-bearing, staleness, freshness
### Sediment
_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
_Avoid_: accretion, bloat, cruft, rot
### No-Op
_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
_Avoid_: redundant instruction, restating the obvious, belaboring
scripts/inspect-description.ts#!/usr/bin/env bun
import { promises as fs } from "node:fs";
import os from "node:os";
import path from "node:path";
const MIN_DESCRIPTION_CHARS = 50;
const MAX_DESCRIPTION_CHARS = 300;
const MAX_NAME_CHARS = 64;
const MIN_OPENAI_SHORT_DESCRIPTION_CHARS = 25;
const MAX_OPENAI_SHORT_DESCRIPTION_CHARS = 64;
type YamlValue = boolean | number | string | string[] | Record<string, unknown>;
type ParsedFrontmatter = {
duplicateKeys: string[];
keys: string[];
values: Map<string, YamlValue>;
};
type Finding = {
file: string;
message: string;
severity: "error" | "warning";
};
const allowedSkillFields = new Set([
"agent",
"allow_implicit_invocation",
"allowed-tools",
"argument-hint",
"arguments",
"category",
"context",
"description",
"disable-model-invocation",
"effort",
"hooks",
"license",
"metadata",
"model",
"name",
"paths",
"tags",
"user-invocable",
"version",
"author",
"color",
]);
const allowedModelAliases = new Set(["haiku", "sonnet", "opus", "inherit"]);
const allowedEfforts = new Set(["low", "medium", "high", "xhigh", "max"]);
function expandHome(input: string): string {
if (input === "~") {
return os.homedir();
}
if (input.startsWith("~/")) {
return path.join(os.homedir(), input.slice(2));
}
return input;
}
async function pathExists(targetPath: string): Promise<boolean> {
try {
await fs.access(targetPath);
return true;
} catch {
return false;
}
}
function charCount(value: string): number {
return Array.from(value).length;
}
function stripWrappingQuotes(value: string): string {
const trimmed = value.trim();
const first = trimmed.at(0);
const last = trimmed.at(-1);
if ((first === "\"" && last === "\"") || (first === "'" && last === "'")) {
return trimmed.slice(1, -1);
}
return trimmed;
}
function parseScalar(rawValue: string): YamlValue {
const trimmed = rawValue.trim();
if (trimmed === "true") {
return true;
}
if (trimmed === "false") {
return false;
}
if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
return Number(trimmed);
}
if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
const body = trimmed.slice(1, -1).trim();
if (!body) {
return [];
}
return body.split(",").map((item) => stripWrappingQuotes(item.trim()));
}
return stripWrappingQuotes(trimmed);
}
function readFrontmatter(markdown: string): string | null {
const frontmatterMatch = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
return frontmatterMatch?.[1] ?? null;
}
function parseTopLevelYaml(yaml: string): ParsedFrontmatter {
const lines = yaml.split(/\r?\n/);
const values = new Map<string, YamlValue>();
const keys: string[] = [];
const duplicateKeys: string[] = [];
for (let index = 0; index < lines.length; index += 1) {
const line = lines[index];
if (!line.trim() || line.trim().startsWith("#") || /^\s/.test(line)) {
continue;
}
const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
if (!match) {
continue;
}
const key = match[1];
const rawValue = match[2].trim();
if (values.has(key)) {
duplicateKeys.push(key);
}
keys.push(key);
if (rawValue === "|" || rawValue === ">" || rawValue === "|-" || rawValue === ">-") {
const blockLines: string[] = [];
for (let blockIndex = index + 1; blockIndex < lines.length; blockIndex += 1) {
const blockLine = lines[blockIndex];
if (/^[A-Za-z0-9_-]+:\s*/.test(blockLine)) {
break;
}
blockLines.push(blockLine.trim());
index = blockIndex;
}
values.set(key, blockLines.join(rawValue.startsWith(">") ? " " : "\n").trim());
continue;
}
if (rawValue === "") {
const listValues: string[] = [];
let sawList = false;
for (let blockIndex = index + 1; blockIndex < lines.length; blockIndex += 1) {
const blockLine = lines[blockIndex];
if (/^[A-Za-z0-9_-]+:\s*/.test(blockLine)) {
break;
}
const listMatch = blockLine.match(/^\s*-\s*(.+)$/);
if (listMatch) {
sawList = true;
listValues.push(stripWrappingQuotes(listMatch[1]));
index = blockIndex;
}
}
values.set(key, sawList ? listValues : {});
continue;
}
values.set(key, parseScalar(rawValue));
}
return { duplicateKeys, keys, values };
}
async function statFollowSymlink(targetPath: string): Promise<{ isDirectory: boolean; isFile: boolean } | null> {
try {
const stat = await fs.stat(targetPath);
return {
isDirectory: stat.isDirectory(),
isFile: stat.isFile(),
};
} catch {
return null;
}
}
async function findSkillFiles(root: string): Promise<string[]> {
const files: string[] = [];
const visitedDirectories = new Set<string>();
const visitedFiles = new Set<string>();
async function walk(currentPath: string): Promise<void> {
const realDirectory = await fs.realpath(currentPath).catch(() => currentPath);
if (visitedDirectories.has(realDirectory)) {
return;
}
visitedDirectories.add(realDirectory);
const entries = await fs.readdir(currentPath, { withFileTypes: true });
for (const entry of entries) {
if (entry.name === "node_modules" || entry.name === ".git") {
continue;
}
const entryPath = path.join(currentPath, entry.name);
const stat = entry.isSymbolicLink()
? await statFollowSymlink(entryPath)
: { isDirectory: entry.isDirectory(), isFile: entry.isFile() };
if (!stat) {
continue;
}
if (stat.isDirectory) {
await walk(entryPath);
continue;
}
if (stat.isFile && entry.name === "SKILL.md") {
const realFile = await fs.realpath(entryPath).catch(() => entryPath);
if (!visitedFiles.has(realFile)) {
visitedFiles.add(realFile);
files.push(entryPath);
}
}
}
}
await walk(root);
return files;
}
async function findCursorRuleFiles(root: string): Promise<string[]> {
const files: string[] = [];
async function walk(currentPath: string): Promise<void> {
const entries = await fs.readdir(currentPath, { withFileTypes: true });
for (const entry of entries) {
if (entry.name === "node_modules" || entry.name === ".git") {
continue;
}
const entryPath = path.join(currentPath, entry.name);
if (entry.isDirectory()) {
await walk(entryPath);
continue;
}
if (entry.isFile() && /\.(md|mdc)$/.test(entry.name)) {
files.push(entryPath);
}
}
}
await walk(root);
return files;
}
function addFinding(findings: Finding[], severity: Finding["severity"], file: string, message: string): void {
findings.push({ file, message, severity });
}
function getString(values: Map<string, YamlValue>, key: string): string | null {
const value = values.get(key);
return typeof value === "string" ? value : null;
}
function isStringList(value: YamlValue | undefined): value is string[] {
return Array.isArray(value) && value.every((item) => typeof item === "string");
}
function validateDescription(findings: Finding[], file: string, name: string, description: string | null): void {
if (!description) {
addFinding(findings, "error", file, `${name} has no description`);
return;
}
const length = charCount(description);
if (length < MIN_DESCRIPTION_CHARS) {
addFinding(findings, "error", file, `${name} description is too short (${length}/${MIN_DESCRIPTION_CHARS} chars min)`);
}
if (length > MAX_DESCRIPTION_CHARS) {
addFinding(findings, "error", file, `${name} description is too long (${length}/${MAX_DESCRIPTION_CHARS} chars max)`);
}
if (/<[A-Za-z][^>]*>/.test(description)) {
addFinding(findings, "error", file, `${name} description must not contain XML or HTML tags`);
}
}
function validateSkillFrontmatter(findings: Finding[], file: string, frontmatter: ParsedFrontmatter): string {
const fallbackName = path.basename(path.dirname(file));
const name = getString(frontmatter.values, "name") ?? fallbackName;
for (const key of frontmatter.duplicateKeys) {
addFinding(findings, "error", file, `duplicate frontmatter key: ${key}`);
}
for (const key of frontmatter.keys) {
if (!allowedSkillFields.has(key)) {
addFinding(findings, "warning", file, `unknown SKILL.md frontmatter key: ${key}`);
}
}
const rawName = frontmatter.values.get("name");
if (typeof rawName !== "string" || rawName.trim() === "") {
addFinding(findings, "error", file, "name must be a non-empty string");
} else {
if (charCount(rawName) > MAX_NAME_CHARS) {
addFinding(findings, "error", file, `${rawName} name is too long (${charCount(rawName)}/${MAX_NAME_CHARS} chars max)`);
}
if (!/^[a-z0-9][a-z0-9-]*$/.test(rawName)) {
addFinding(findings, "error", file, `${rawName} name must use lowercase letters, numbers, and hyphens only`);
}
}
validateDescription(findings, file, name, getString(frontmatter.values, "description"));
for (const key of ["disable-model-invocation", "user-invocable", "allow_implicit_invocation"]) {
const value = frontmatter.values.get(key);
if (value !== undefined && typeof value !== "boolean") {
addFinding(findings, "error", file, `${key} must be a boolean`);
}
}
const allowedTools = frontmatter.values.get("allowed-tools");
if (allowedTools !== undefined) {
if (typeof allowedTools !== "string" && !isStringList(allowedTools)) {
addFinding(findings, "error", file, "allowed-tools must be a string or a YAML list of strings");
}
if (isStringList(allowedTools) && allowedTools.some((tool) => tool.trim() === "")) {
addFinding(findings, "error", file, "allowed-tools contains an empty tool entry");
}
}
const argumentHint = frontmatter.values.get("argument-hint");
if (argumentHint !== undefined && typeof argumentHint !== "string") {
addFinding(findings, "error", file, "argument-hint must be a string; quote values that use [] syntax");
}
for (const key of ["arguments", "paths", "tags"]) {
const value = frontmatter.values.get(key);
if (value !== undefined && typeof value !== "string" && !isStringList(value)) {
addFinding(findings, "error", file, `${key} must be a string or a YAML list of strings`);
}
}
const context = frontmatter.values.get("context");
if (context !== undefined && context !== "fork") {
addFinding(findings, "error", file, "context must be \"fork\" when present");
}
const agent = frontmatter.values.get("agent");
if (agent !== undefined && typeof agent !== "string") {
addFinding(findings, "error", file, "agent must be a string");
}
const model = frontmatter.values.get("model");
if (model !== undefined) {
if (typeof model !== "string") {
addFinding(findings, "error", file, "model must be a string");
} else if (!allowedModelAliases.has(model) && !/^claude-[a-z0-9.-]+$/.test(model)) {
addFinding(findings, "warning", file, `model value is not a common Claude alias or model id: ${model}`);
}
}
const effort = frontmatter.values.get("effort");
if (effort !== undefined && (typeof effort !== "string" || !allowedEfforts.has(effort))) {
addFinding(findings, "error", file, `effort must be one of: ${Array.from(allowedEfforts).join(", ")}`);
}
return name;
}
async function validateSkillShape(findings: Finding[], skillFile: string): Promise<void> {
const skillDir = path.dirname(skillFile);
const entries = await fs.readdir(skillDir, { withFileTypes: true });
for (const entry of entries) {
if (entry.name === "SKILL.md") {
continue;
}
if (entry.name === "agents" || entry.name === "assets" || entry.name === "references" || entry.name === "scripts") {
if (!entry.isDirectory()) {
addFinding(findings, "error", path.join(skillDir, entry.name), `${entry.name} must be a directory`);
}
continue;
}
// Skills may bundle extra runtime references or upstream repo files. Shape
// validation only enforces required files and known structured locations.
}
const openaiYaml = path.join(skillDir, "agents", "openai.yaml");
if (await pathExists(openaiYaml)) {
await validateOpenAiYaml(findings, openaiYaml, path.basename(skillDir));
}
}
function getTopLevelKeys(yaml: string): string[] {
return yaml
.split(/\r?\n/)
.map((line) => line.match(/^([A-Za-z0-9_-]+):\s*/)?.[1])
.filter((key): key is string => Boolean(key));
}
function getNestedScalar(yaml: string, section: string, key: string): string | boolean | null {
const lines = yaml.split(/\r?\n/);
let inSection = false;
for (const line of lines) {
if (/^[A-Za-z0-9_-]+:\s*/.test(line)) {
inSection = line.startsWith(`${section}:`);
continue;
}
if (!inSection) {
continue;
}
const match = line.match(new RegExp(`^\\s{2}${key}:\\s*(.*)$`));
if (!match) {
continue;
}
const value = parseScalar(match[1]);
return typeof value === "boolean" ? value : String(value);
}
return null;
}
function getOpenAiToolEntries(yaml: string): Array<Record<string, string>> {
const lines = yaml.split(/\r?\n/);
const tools: Array<Record<string, string>> = [];
let inTools = false;
let current: Record<string, string> | null = null;
for (const line of lines) {
if (/^[A-Za-z0-9_-]+:\s*/.test(line)) {
inTools = false;
}
if (/^\s{2}tools:\s*$/.test(line)) {
inTools = true;
continue;
}
if (!inTools) {
continue;
}
const startMatch = line.match(/^\s{4}-\s*([A-Za-z0-9_-]+):\s*(.+)$/);
if (startMatch) {
current = { [startMatch[1]]: String(parseScalar(startMatch[2])) };
tools.push(current);
continue;
}
const fieldMatch = line.match(/^\s{6}([A-Za-z0-9_-]+):\s*(.+)$/);
if (fieldMatch && current) {
current[fieldMatch[1]] = String(parseScalar(fieldMatch[2]));
}
}
return tools;
}
async function validateOpenAiYaml(findings: Finding[], file: string, skillName: string): Promise<void> {
const yaml = await fs.readFile(file, "utf8");
const allowedTopLevelKeys = new Set(["dependencies", "interface", "policy"]);
for (const key of getTopLevelKeys(yaml)) {
if (!allowedTopLevelKeys.has(key)) {
addFinding(findings, "error", file, `unknown agents/openai.yaml top-level key: ${key}`);
}
}
const displayName = getNestedScalar(yaml, "interface", "display_name");
if (displayName !== null && typeof displayName !== "string") {
addFinding(findings, "error", file, "interface.display_name must be a string");
}
const shortDescription = getNestedScalar(yaml, "interface", "short_description");
if (shortDescription !== null) {
if (typeof shortDescription !== "string") {
addFinding(findings, "error", file, "interface.short_description must be a string");
} else {
const length = charCount(shortDescription);
if (length < MIN_OPENAI_SHORT_DESCRIPTION_CHARS || length > MAX_OPENAI_SHORT_DESCRIPTION_CHARS) {
addFinding(
findings,
"error",
file,
`interface.short_description must be ${MIN_OPENAI_SHORT_DESCRIPTION_CHARS}-${MAX_OPENAI_SHORT_DESCRIPTION_CHARS} chars (${length} found)`,
);
}
}
}
const defaultPrompt = getNestedScalar(yaml, "interface", "default_prompt");
if (defaultPrompt !== null) {
if (typeof defaultPrompt !== "string") {
addFinding(findings, "error", file, "interface.default_prompt must be a string");
} else if (!defaultPrompt.includes(`$${skillName}`)) {
addFinding(findings, "error", file, `interface.default_prompt must mention $${skillName}`);
}
}
const brandColor = getNestedScalar(yaml, "interface", "brand_color");
if (brandColor !== null && (typeof brandColor !== "string" || !/^#[0-9A-Fa-f]{6}$/.test(brandColor))) {
addFinding(findings, "error", file, "interface.brand_color must be a #RRGGBB hex color");
}
for (const iconField of ["icon_small", "icon_large"]) {
const iconPath = getNestedScalar(yaml, "interface", iconField);
if (iconPath === null) {
continue;
}
if (typeof iconPath !== "string" || !iconPath.startsWith("./assets/")) {
addFinding(findings, "error", file, `interface.${iconField} must be a ./assets/... path`);
continue;
}
const absoluteIconPath = path.resolve(path.dirname(file), "..", iconPath);
if (!(await pathExists(absoluteIconPath))) {
addFinding(findings, "error", file, `interface.${iconField} does not exist: ${iconPath}`);
}
}
const allowImplicitInvocation = getNestedScalar(yaml, "policy", "allow_implicit_invocation");
if (allowImplicitInvocation !== null && typeof allowImplicitInvocation !== "boolean") {
addFinding(findings, "error", file, "policy.allow_implicit_invocation must be a boolean");
}
for (const tool of getOpenAiToolEntries(yaml)) {
for (const requiredField of ["type", "value", "description", "transport", "url"]) {
if (!tool[requiredField]) {
addFinding(findings, "error", file, `dependencies.tools entry is missing ${requiredField}`);
}
}
if (tool.type && tool.type !== "mcp") {
addFinding(findings, "error", file, "dependencies.tools[].type must be \"mcp\"");
}
if (tool.transport && tool.transport !== "streamable_http") {
addFinding(findings, "error", file, "dependencies.tools[].transport must be \"streamable_http\"");
}
if (tool.url && !tool.url.startsWith("https://")) {
addFinding(findings, "error", file, "dependencies.tools[].url must be an HTTPS URL");
}
}
}
async function validateSkillFile(file: string): Promise<Finding[]> {
const findings: Finding[] = [];
const markdown = await fs.readFile(file, "utf8");
const frontmatter = readFrontmatter(markdown);
if (!frontmatter) {
addFinding(findings, "error", file, "SKILL.md must start with YAML frontmatter delimited by ---");
return findings;
}
const parsedFrontmatter = parseTopLevelYaml(frontmatter);
validateSkillFrontmatter(findings, file, parsedFrontmatter);
const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, "").trim();
if (!body) {
addFinding(findings, "error", file, "SKILL.md body must not be empty");
}
await validateSkillShape(findings, file);
return findings;
}
async function validateCursorRuleFile(file: string): Promise<Finding[]> {
const findings: Finding[] = [];
const markdown = await fs.readFile(file, "utf8");
const frontmatter = readFrontmatter(markdown);
if (!frontmatter) {
return findings;
}
const parsedFrontmatter = parseTopLevelYaml(frontmatter);
const allowedCursorFields = new Set(["alwaysApply", "description", "globs"]);
for (const key of parsedFrontmatter.duplicateKeys) {
addFinding(findings, "error", file, `duplicate Cursor rule frontmatter key: ${key}`);
}
for (const key of parsedFrontmatter.keys) {
if (!allowedCursorFields.has(key)) {
addFinding(findings, "error", file, `unknown Cursor rule frontmatter key: ${key}`);
}
}
const alwaysApply = parsedFrontmatter.values.get("alwaysApply");
if (alwaysApply !== undefined && typeof alwaysApply !== "boolean") {
addFinding(findings, "error", file, "alwaysApply must be a boolean");
}
const description = getString(parsedFrontmatter.values, "description");
if (description) {
validateDescription(findings, file, path.basename(file), description);
}
const globs = parsedFrontmatter.values.get("globs");
if (globs !== undefined && typeof globs !== "string" && !isStringList(globs)) {
addFinding(findings, "error", file, "globs must be a string or YAML list of strings");
}
return findings;
}
async function collectSkillFiles(roots: string[]): Promise<string[]> {
const files = (await Promise.all(roots.map(findSkillFiles))).flat().sort();
return files;
}
async function collectCursorRuleFiles(roots: string[]): Promise<string[]> {
const cursorRoots = roots.filter((root) => root.includes(`${path.sep}.cursor${path.sep}rules`) || root.endsWith(`${path.sep}.cursor${path.sep}rules`));
if (cursorRoots.length === 0) {
return [];
}
return (await Promise.all(cursorRoots.map(findCursorRuleFiles))).flat().sort();
}
async function main(): Promise<void> {
const roots = process.argv.slice(2).map((arg) => path.resolve(expandHome(arg)));
const defaultRoots = [path.join(os.homedir(), ".agents", "skills")];
const rootsToInspect = roots.length > 0 ? roots : defaultRoots;
const existingRoots = [];
for (const root of rootsToInspect) {
if (await pathExists(root)) {
existingRoots.push(root);
}
}
if (existingRoots.length === 0) {
console.error(`No roots found: ${rootsToInspect.join(", ")}`);
process.exitCode = 2;
return;
}
const skillFiles = await collectSkillFiles(existingRoots);
const cursorRuleFiles = await collectCursorRuleFiles(existingRoots);
const allFindings = [
...(await Promise.all(skillFiles.map(validateSkillFile))).flat(),
...(await Promise.all(cursorRuleFiles.map(validateCursorRuleFile))).flat(),
];
const errors = allFindings.filter((finding) => finding.severity === "error");
const warnings = allFindings.filter((finding) => finding.severity === "warning");
for (const finding of allFindings) {
const prefix = finding.severity === "error" ? "error" : "warning";
console.warn(`${prefix}: ${finding.message} (${finding.file})`);
}
if (errors.length === 0) {
const warningSuffix = warnings.length === 0 ? "" : ` with ${warnings.length} warning(s)`;
const cursorSuffix = cursorRuleFiles.length === 0 ? "" : ` and ${cursorRuleFiles.length} Cursor rule(s)`;
console.log(`OK: ${skillFiles.length} skill(s)${cursorSuffix} passed validation${warningSuffix}.`);
return;
}
console.error(`Found ${errors.length} error(s) and ${warnings.length} warning(s) across ${skillFiles.length} skill(s).`);
process.exitCode = 1;
}
main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 2;
});
scripts/setup-codex-icons.ts#!/usr/bin/env bun
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
const root = process.argv[2] ?? join(process.env.HOME ?? "", ".agents/skills");
const lucideRoot = process.argv[3];
if (!lucideRoot) {
throw new Error("Pass the lucide-static icons directory as the second argument.");
}
function titleize(slug: string): string {
return slug
.replace(/[-_]+/g, " ")
.replace(/\b\w/g, (character) => character.toUpperCase());
}
function iconName(slug: string): string {
const rules: Array<[RegExp, string]> = [
[/^apex$/, "mountain"],
[/debug|doctor|incident|fix-errors/, "bug"],
[/review|audit|critique|check-/, "scan-search"],
[/commit/, "git-commit-horizontal"],
[/merge|pull-request|create-pr|fix-pr/, "git-merge"],
[/browser|chrome|web-perf/, "globe"],
[/code|sdk|api|cli|shell|terminal/, "terminal"],
[/agent|fable|ultrathink/, "bot"],
[/image|icon|gemini|visual/, "image"],
[/animate|video|tella/, "clapperboard"],
[/design|style|interface|shadcn|mobile-dialog/, "palette"],
[/copy|grammar|article|prompt|clarify/, "pen-line"],
[/mail|lumail|frontapp/, "mail"],
[/auth|security|safe-ship/, "shield-check"],
[/database|postgres|convex/, "database"],
[/cloudflare|deploy|appstore/, "cloud-upload"],
[/stripe|mercury|marketing|product/, "badge-dollar-sign"],
[/analytics|posthog|umami|optimize/, "chart-no-axes-combined"],
[/search|find-docs|exa/, "search"],
[/docs|notion|rules|skill-manager/, "notebook-tabs"],
[/skill|hook|config|settings|environment|setup/, "settings"],
[/memory|continue-conversation/, "brain"],
[/team|subagent/, "users"],
[/calendar|loop|babysit|monitor/, "clock-3"],
[/tweet|typefully/, "send"],
[/saveit|bookmark/, "bookmark"],
[/seo|web-design/, "scan-text"],
[/refactor|clean-code|improve/, "wand-sparkles"],
[/architecture|prototype|builder|create/, "blocks"],
[/extract|migrate/, "package-open"],
[/translate|traduction/, "languages"],
];
return rules.find(([pattern]) => pattern.test(slug))?.[1] ?? "sparkles";
}
async function iconSvg(slug: string): Promise<string> {
const name = iconName(slug);
const source = await readFile(join(lucideRoot, `${name}.svg`), "utf8");
return source
.replace("<svg", `<svg role="img" aria-label="${slug} skill icon"`)
.replace(/width="24"/, 'width="128"')
.replace(/height="24"/, 'height="128"')
.replaceAll('stroke="currentColor"', 'stroke="#F5F5F5"');
}
function frontmatter(markdown: string, key: string): string | undefined {
const match = markdown.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
return match?.[1].trim().replace(/^['"]|['"]$/g, "");
}
function shortDescription(markdown: string, displayName: string): string {
const raw = frontmatter(markdown, "description") ?? `Use the ${displayName} skill in Codex`;
const sentence = raw.replace(/\s+/g, " ").split(/(?<=[.!?])\s/)[0].replace(/[.!?]+$/, "");
const fallback = `Use ${displayName} workflows in Codex`;
const value = sentence.length >= 25 ? sentence : fallback;
if (value.length <= 64) return value;
const clipped = value.slice(0, 61).replace(/\s+\S*$/, "");
return `${clipped}...`;
}
function addIconMetadata(yaml: string, iconPath: string): string {
if (/^\s+icon_small:/m.test(yaml) || !/^interface:\s*$/m.test(yaml)) return yaml;
const lines = yaml.trimEnd().split("\n");
const interfaceIndex = lines.findIndex((line) => line === "interface:");
let insertAt = interfaceIndex + 1;
while (insertAt < lines.length && (/^\s{2}\S/.test(lines[insertAt]) || lines[insertAt] === "")) insertAt++;
const metadata = [
` icon_small: "${iconPath}"`,
` icon_large: "${iconPath}"`,
];
if (!/^\s+brand_color:/m.test(yaml)) metadata.push(' brand_color: "#F5F5F5"');
lines.splice(insertAt, 0, ...metadata);
return `${lines.join("\n")}\n`;
}
const entries = await readdir(root, { withFileTypes: true });
let created = 0;
let augmented = 0;
let preserved = 0;
for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
const skillDir = join(root, entry.name);
let markdown: string;
try {
markdown = await readFile(join(skillDir, "SKILL.md"), "utf8");
} catch {
continue;
}
const slug = frontmatter(markdown, "name") ?? entry.name;
const displayName = titleize(slug);
const iconPath = "./assets/codex-icon.svg";
const agentsDir = join(skillDir, "agents");
const assetsDir = join(skillDir, "assets");
const yamlPath = join(agentsDir, "openai.yaml");
await mkdir(agentsDir, { recursive: true });
let yaml: string | undefined;
try {
yaml = await readFile(yamlPath, "utf8");
} catch {}
if (yaml && /^\s+icon_small:/m.test(yaml) && !yaml.includes(iconPath)) {
preserved++;
continue;
}
await mkdir(assetsDir, { recursive: true });
await writeFile(join(assetsDir, "codex-icon.svg"), await iconSvg(slug), "utf8");
if (yaml) {
await writeFile(yamlPath, addIconMetadata(yaml, iconPath), "utf8");
augmented++;
continue;
}
const generated = `interface:\n display_name: "${displayName.replaceAll('"', '\\"')}"\n short_description: "${shortDescription(markdown, displayName).replaceAll('"', '\\"')}"\n icon_small: "${iconPath}"\n icon_large: "${iconPath}"\n brand_color: "#F5F5F5"\n default_prompt: "Use $${slug} to help with this task."\n`;
await writeFile(yamlPath, generated, "utf8");
created++;
}
console.log(JSON.stringify({ root, created, augmented, preserved, total: created + augmented + preserved }, null, 2));
SKILL.md--- name: skill-manager description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and skill discovery. --- 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 1. Confirm 2–3 trigger prompts with the user. 2. Pick the platform. Default from the path: `.claude` → Claude, `.agents` → Codex, `.cursor` → Cursor. Ask if unclear. 3. Write frontmatter, then the body: inspect → act → return → stop. 4. Run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root. Personal skills live in `~/.agents/skills/<name>/`. Platform layout and frontmatter: [claude-code.md](references/claude-code.md), [codex.md](references/codex.md), [cursor.md](references/cursor.md). Description rules: [description-recommandation.md](references/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`.