Skills

A skill is the authoring unit for a reusable procedure or body of expertise. It is appropriate when a task needs more than a stable fact or command: ordered steps, conditional judgement, optional references, templates, or supporting scripts.

When to use a skill

Use a skill for repeated workflows such as change verification, documentation drift review, implementation strategy, integration testing, release review, coverage improvement, migration planning, incident diagnosis, or PR handoff.

Do not create a skill for:

one fact every task must know—put that in scoped instructions;
one deterministic operation—provide a script or CLI;
an automatic event reaction—use a hook;
live external state—provide an MCP tool, optionally orchestrated by a skill;
a one-off task—keep its constraints in the prompt or durable plan.

Author the contract

Every skill should state:

the user request or repository state that should trigger it;
neighboring cases that must not trigger it;
required inputs, preconditions, and supported scope;
ordered steps and decision points;
allowed tools, side effects, and approval boundaries;
expected output or artifact;
success, partial-success, and failure conditions;
which references, assets, or scripts to load and when.

The description is routing metadata. Front-load request-like trigger words and include exclusions or negative examples when skills overlap. Both vendors may shorten descriptions when many skills compete for the discovery budget, so the essential use case must survive truncation.

File layout

<skill-name>/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

SKILL.md is required. Keep it a concise workflow rather than a reference dump; Anthropic recommends fewer than 500 lines. Put deterministic helpers in scripts/, detailed knowledge and examples in references/, and templates in assets/.

OpenAI’s optional agents/openai.yaml can provide display metadata, a default prompt, invocation policy, and MCP dependencies:

interface:
  display_name: Verify change
  short_description: Run and interpret the checks required by a change
  default_prompt: Verify this change and report evidence.

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: mcp
      value: example-server
      description: External evidence required by the workflow
      transport: streamable_http
      url: https://example.invalid/mcp

Set implicit invocation to false for destructive, deployment, publication, commit, or outbound-message workflows where a user must deliberately select the capability.

Repository placement

OpenAI Codex scans .agents/skills from the current working directory up to the repository root. Place repo-wide workflows at $REPO_ROOT/.agents/skills/<name> and subsystem workflows in the applicable subtree. User-wide skills belong in $HOME/.agents/skills; admin defaults may live in /etc/codex/skills.

Claude Code uses .claude/skills/<name> for project skills and also supports personal, managed, nested, and plugin scopes. Its product-specific metadata can control manual/model invocation, allowed tools, model and effort, isolated subagent execution, path activation, and skill hooks.

Its invocation controls are not interchangeable:

Default: the user and model can invoke the skill, and discovery metadata is loaded.
disable-model-invocation: true: the user can invoke the skill, the model cannot, and discovery metadata is not loaded.
user-invocable: false: the model can invoke the skill, the user cannot, and discovery metadata is loaded.

allowed-tools pre-approves listed tools while the skill is active; it does not restrict the remaining tool set. Use permission denies for prohibition.

For cross-client workflows, keep the procedural core compatible with the Agent Skills standard and isolate vendor controls. Use a generated mirror or plugin packaging rather than editing two independent bodies of instructions.

Compose skills with scripts and tools

Use the model for scope selection, interpretation, comparison, prioritization, and explanation. Use scripts for repeated mechanics in a fixed order: format, lint, type-check, test, collect diffs, query structured status, or produce an artifact manifest.

A skill that calls MCP should name the required tools and explain what evidence to obtain before any mutation. The MCP server owns authentication and external authority; the skill owns the procedure. Never imply that selecting a skill expands tool permissions.

For generated outputs, edit the declared source and run the generator. Teach the skill how to find the source and regeneration command, not how to patch the generated artifact.

Treat dynamic context as execution. Claude skills can run shell preprocessing before the model receives the rendered workflow, which is useful for current diffs or environment versions but creates a code-execution and trust boundary. Review those commands, keep inserted output bounded, and allow managed policy to disable skill shell execution where required.

Invocation and enforcement

Implicit routing is a convenience, not a completion guarantee. If a workflow is mandatory, add a short conditional rule to the applicable root or nested instructions, for example:

If runtime behavior, tests, examples, or build output changes, invoke the
verify-change skill and do not report completion until its applicable checks
pass.

Keep CI or another deterministic gate for requirements that must hold even if the skill is not selected. Explicit invocation is also preferable when the task has side effects or when repeatability matters more than conversational convenience.

Evaluation

Evaluate routing separately from execution:

positive prompts that should select the skill;
negative prompts that resemble it but should not;
ambiguous prompts requiring a clarifying choice;
explicit invocations;
outcome assertions for artifacts, commands, approvals, and final evidence;
with-skill and without-skill baselines in fresh contexts;
duration, token, and tool-call measurements.

Retest after changing the description, adding nearby skills, changing models, or packaging the skill. Track unused or chronically misrouted skills and retire or consolidate them before raising discovery budgets.

Long-session lifecycle

Once selected, a skill body remains in conversation context rather than being reread from disk on every turn. Claude Code’s documented compaction behaviour reattaches the newest invocation of each skill, retaining up to 5,000 tokens per skill within a 25,000-token combined budget. Older skills can be dropped. Keep SKILL.md concise, save decisions and progress to durable artifacts, and test a workflow across compaction instead of assuming the complete procedure will remain present indefinitely.

For completion-critical workflows, use the repository’s exact ordered command stack rather than a generic “run tests.” OpenAI’s Agents SDK case study, for example, encoded install, build, package build checks, distribution checks, lint, and tests in a fixed order and made the conditional trigger explicit in AGENTS.md.

Promotion checklist

A repo skill is ready for plugin distribution only when it has a stable name and contract, owned scripts, routing and outcome tests, documented tool dependencies, explicit side effects, clean-environment validation, a versioning plan, and more than one real consumer.

Sources: OpenAI Build skills, OpenAI customization, Anthropic skills, and the OpenAI Agents SDK case study.