Agent Skill Management

Use this capability whenever you add, edit, rename, move, or remove an agent skill in a project that holds its skills in two tiers. Distributable skills — portable capabilities other projects can install — are authored in a source directory (conventionally skills/, the source of truth) and installed into the skill root (the directory the agent actually loads — .claude/skills/ for Claude Code, .agents/skills/ for Codex and several others) with the vercel-labs/skills CLI (npx skills); a skills-lock.json file records what was installed. Repository-local skills — capabilities that encode a single project's own process and have to fire while a surface is being edited, never a document the project's own instructions could route to on demand — are committed directly under the skill root and are never touched by the CLI.

Discovery is what routes to a skill in either tier: each skill advertises when it applies through its own description, so no written index is required. Some hosts maintain one anyway (e.g. an AGENTS.md table), which then becomes a second record to keep current.

This skill is self-contained: it names no repository-specific file or layout and references no repository-root index, so it works installed on its own. The directory names below are the conventional defaults — skills/ for the source, and a skill root of .claude/skills/ on Claude Code or .agents/skills/ on Codex. Substitute the host project's chosen paths where they differ, and note that a project targeting both hosts has two roots, one of which may be a symlink into the other.

Guidelines:

• MUST, where the host project maintains a written skill index, keep it in sync whenever a skill in either tier is added, renamed, moved, or removed, per your project's skill-authoring conventions; where it maintains none, each skill's description frontmatter is the whole of discovery and no index is owed.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Is the Material a Skill?

Before asking which tier a skill belongs in, ask whether the material should be a skill at all. A skill's one functional advantage over a document is discovery — it fires unasked while a matching surface is being edited, without anyone remembering to consult it — and that advantage is also its whole recurring cost: every skill's description competes for room in every session's listing, on every task, whether or not that task needs it. Material that never has to fire unasked pays that cost for nothing, because an always-loaded instruction file can route to it on demand instead.