Agent skills: teach your coding agent once, apply everywhere

Every team that uses coding agents eventually hits the same wall: the same instructions get pasted into every session. The PR review checklist. The commit message format. The architecture constraints. The testing standards.

Agent skills are the answer. A skill is written once, stored as a markdown file, and loaded only when the current request matches its description — no repeated pasting, no context bloat from irrelevant workflows. Skills are defined by an open standard and supported across Codex, Claude Code, and other agent platforms.

What a skill actually is

At its simplest, a skill is a directory containing a SKILL.md file with two parts: frontmatter and body. The frontmatter gives the skill a name and description. The description matters most because the agent uses it to decide when the skill applies.

---
name: pr-review
description: Reviews pull requests for code quality, security issues, and test
  coverage. Use when asked to review a PR or check code changes.
---

When reviewing a PR:
1. Run `git diff main...HEAD` to see all changes
2. Check for:
   - Security vulnerabilities (injection, auth bypass, data exposure)
   - Missing error handling and edge cases
   - Test coverage gaps for new code paths
   - Breaking changes to public APIs
3. Report findings organized by severity
4. Include specific file paths and line references

That’s it. No registry, no build step, no package manager. A markdown file in the right directory is a working skill.

The paths differ by platform:

• Codex: .codex/agents/skills/<name>/SKILL.md (project) or ~/.agents/skills/<name>/SKILL.md (user)
• Claude Code: .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (user)

How skills activate

Skills don’t all load at session start — only their names and descriptions do. The full instructions stay on disk until a request matches.

Implicit invocation

The agent matches your request against available skill descriptions and activates the right one automatically. “Review this PR” matches a skill described as “Reviews pull requests for code quality.” “Write a commit” matches a skill described as “Formats git commits following conventional commit standards.”

Claude Code uses semantic matching — intent overlap, not just keyword matching. Codex uses description-based triggering. In both cases, the description is the only surface the agent uses to decide when to activate a skill. A vague description (“Helps with code”) won’t match specific requests. A concrete description (“Reviews pull requests for code quality, security issues, and test coverage”) matches reliably.

Explicit invocation

You can also name a skill directly:

• Codex CLI: Type $ to mention a skill or run /skills to browse
• Claude Code: Reference by name or use the skill selector

Explicit invocation loads the full instructions immediately. Implicit invocation waits for a description match.

Controlling invocation

Not every skill should activate automatically. Restrict a skill to explicit invocation only:

policy:
  allow_implicit_invocation: false

With allow_implicit_invocation: false, the skill only activates when explicitly named. Use this for skills with side effects, production access, or destructive operations.

Claude Code skills can set allowed-tools to restrict what the agent can do when the skill is active. A codebase-onboarding skill with allowed-tools: Read, Grep, Glob, Bash can explain a repository without modifying files.

Progressive disclosure: why skills don’t bloat the context window

Skills use a three-stage loading model to keep context windows lean:

At startup, the agent scans all skill directories and reads only names and descriptions. This initial list is capped at roughly 2% of the context window — about 8,000 characters for most models. The full instructions stay on disk until a request matches.

This means you can have dozens of skills installed without crowding out the prompt. A debugging session doesn’t carry the weight of a PR review checklist until the task actually calls for review behavior.

For a deep dive into the progressive disclosure architecture and how the pattern generalizes beyond coding agents, see the companion post on progressive disclosure as a design pattern.

Where skills live (scope hierarchy)

Where you save a skill determines who can use it. Both platforms support layered scopes:

Repository-scoped skills are committed to version control — the repo carries its own task knowledge. User-scoped skills are personal preferences: commit message formats, explanation styles, document templates. Admin/enterprise-scoped skills enforce organization-wide standards.

Priority and shadowing

When two skills share the same name, Claude Code applies a priority hierarchy: Enterprise > Personal > Project > Plugins. A personal “code-review” skill shadows a project one with the same name. Codex surfaces both in skill selectors. Either way, use descriptive, unique names (“frontend-review”, “backend-review”) to avoid ambiguity.

Skills vs. everything else

Coding agents have several customization surfaces. Each fits a different persistence pattern:

They’re complementary. A typical setup: CLAUDE.md for global standards, skills for task expertise, hooks for automated checks, subagents for isolated delegation, and plugins for distribution.

Testing a skill

Skills need testing just like code:

1. Test the description — Write 5-10 example prompts that should trigger the skill and 5 that shouldn’t. Verify the boundaries are correct.
2. Test the instructions — Run the skill against a known input and check whether the output follows the procedure. Did it skip steps? Did it stop at the right point?
3. Test with variations — Change the input slightly. Does the skill still produce consistent output?
4. Test the stopping condition — Without explicit stopping criteria, agents tend to keep working. A structured output format in the instructions (“Return your findings as: Summary, Issues, Recommendations”) creates a natural stopping point.

Skills are detected automatically when saved. If changes don’t appear, restart the agent. The iteration cycle: edit SKILL.md → restart → test with a matching prompt → refine.

Distributing skills

Skills authored locally become more valuable when shared:

• Git repository — Commit to .codex/agents/skills/ or .claude/skills/ so the repo carries its own task knowledge.
• Plugins — Package skills for distribution across projects and community marketplaces. A plugin bundles one or more skills, plus optional app integrations and MCP server configuration, into a single installable unit.
• Enterprise managed settings — Deploy mandatory standards organization-wide.

Skills are the authoring format; plugins are the distribution format. You write skills locally, then bundle them as plugins when you’re ready for others to install them.

Enabling and disabling skills

Disable a skill without deleting it. In Codex:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

This is useful when a repo includes skills that don’t apply to your workflow, or when a skill needs maintenance and shouldn’t be used until it’s fixed. Restart after changing the config.

Optional UI metadata

The agents/openai.yaml file controls how the skill appears in the Codex app:

interface:
  display_name: "PR Review"
  short_description: "Review pull requests for quality and security"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Review this PR for code quality and security issues"

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

Tool dependencies declared here help Codex surface missing requirements before the skill activates. If a skill needs an MCP server that isn’t configured, Codex can warn at selection time rather than failing mid-execution.

Troubleshooting

Most skill problems fall into predictable categories:

• Skill doesn’t trigger — The description needs trigger phrases that match real requests.
• Skill doesn’t load — SKILL.md must sit inside a named skill directory, not at the skills root.
• Wrong skill activates — Similar descriptions need sharper boundaries.
• Personal skill is ignored — A higher-priority skill with the same name may be shadowing it.
• Changes aren’t reflected — Skills are scanned at startup. Restart the agent.

Getting started in 10 minutes

1. Identify one task you repeat across sessions — PR review, commit messages, bug triage.
2. Run $skill-creator in Codex CLI (or create the SKILL.md manually in Claude Code). Answer what the skill does, when it triggers, and whether it needs scripts.
3. Save the generated skill and restart.
4. Test with a matching prompt. Does it activate? Does the output follow your procedure?
5. Iterate on the description if activation is unreliable. Iterate on the body if the procedure isn’t followed.
6. Commit repo-scoped skills so the team gets them on next pull.

Start with one skill. A single working skill that triggers reliably teaches you more about the system than reading about ten hypothetical ones.