Agent skills: package task knowledge for coding agents

Repeated agent instructions are a packaging problem. A review checklist, release procedure, or debugging playbook belongs in a discoverable artifact, not in every prompt.

An agent skill provides that artifact: a directory whose SKILL.md declares when the skill applies and contains the procedure to follow. Compatible agents index the metadata first and load the full instructions only when the task needs them.

A skill is a directory contract

The portable core is deliberately small. A skill directory contains SKILL.md with YAML frontmatter and Markdown instructions. Supporting scripts, references, and templates can sit beside it.

---
name: pr-review
description: Reviews a pull request for correctness, security, and missing test
  coverage. Use when asked to review a PR or inspect a proposed change.
---

Inspect the complete change before reporting findings.

1. Identify the merge base and read the full diff.
2. Trace changed public interfaces to their callers.
3. Run the narrowest relevant tests.
4. Report actionable findings by severity with file and line evidence.
5. State the verification performed and any remaining uncertainty.

The description is routing metadata. It should name both the capability and the situations that trigger it. A vague description such as “helps with code” gives the agent no reliable selection signal.

Progressive disclosure protects context

Skills avoid loading every procedure into every turn. Codex starts with each skill’s name, description, and path, then reads SKILL.md after selecting the skill. The skill can direct Codex to additional files only when the current branch of work needs them.

Codex also budgets the initial skills list. The list may consume at most 2% of the model context window, or 8,000 characters when the window size is unknown. At larger scale, descriptions are shortened and some skills can be omitted from the initial list.

That structure makes a skill collection scale better than a single global instruction file. The agent sees a compact capability index instead of every workflow at once.

Invocation differs by agent

The file format is portable; invocation and extension metadata are product-specific.

Codex can disable automatic selection for a skill through agents/openai.yaml:

policy:
  allow_implicit_invocation: false

Claude Code expresses a similar product-specific choice with disable-model-invocation: true in its skill frontmatter. Those controls are not part of the portable Agent Skills core.

Scope determines ownership

Codex discovers repository skills from .agents/skills directories between the current working directory and the repository root. It also reads user skills from ~/.agents/skills, administrator skills from /etc/codex/skills, and bundled system skills.

Use scope as an ownership decision:

A repository skill should travel with the code whose constraints it describes. A user skill should remain useful across unrelated projects. Moving a repository-specific procedure into user scope hides an important dependency from collaborators.

Scripts make deterministic work reusable

Markdown should explain decisions. A script should perform stable mechanical work that would otherwise be regenerated on each invocation.

#!/usr/bin/env bash
set -euo pipefail

npx --yes @redocly/cli lint openapi.yaml

The skill can tell the agent when to run the script, how to interpret failure, and which changes require human review. The script keeps the mechanical check identical across sessions.

Avoid hiding judgment inside a large opaque script. If the work depends on architectural intent or evidence from the current change, keep that reasoning visible in the instructions.

Test selection and execution separately

A skill can fail before its instructions run. Test it in two stages:

1. Selection: Ask for the task without naming the skill. Confirm that the description triggers on relevant prompts and stays silent on adjacent ones.
2. Execution: Invoke the skill explicitly. Confirm that its paths resolve, scripts run, outputs are interpretable, and the procedure reaches a clear stopping condition.

Use one positive prompt, one paraphrase, and one near-miss prompt for selection. For execution, run the procedure in a disposable fixture that contains both a passing and a failing case.

Skills become environment capabilities

Skills are most valuable when the runtime that needs them declares them explicitly. Agent Factory models Skills alongside harnesses, model policy, permissions, variables, MCP tools, and plugins in a Factory Run environment.

That ownership boundary turns a skill from personal prompt folklore into a reproducible capability of the execution environment. A run can declare the knowledge it expects instead of depending on whichever files happen to exist in one operator’s home directory.

Takeaways