AI Agent Skills: Reusable Prompts for Claude Code, Codex, and Copilot

What Are Skills?

A skill is a reusable prompt file that gives an AI coding agent a detailed playbook for a specific task. Instead of typing the same instructions every time you want a code review, deployment setup, or refactor plan, you write the instructions once as a skill and invoke it with a slash command.

Skills sit between one-off chat prompts and full custom tooling. They are:

• Reusable across sessions and team members
• Version-controlled alongside your code
• Scoped to a project, a user, or an organization
• Composable with tools, arguments, and context

All three major AI coding agents now support some form of skills. The implementations differ, but the core idea is the same: a Markdown file with optional frontmatter that tells the agent what to do.

Claude Code

Claude Code has the most mature skills system. Skills are Markdown files with YAML frontmatter stored in a specific directory structure.

Where Skills Live

When skills share the same name across scopes, precedence is enterprise > personal > project.

Claude Code also still supports legacy commands in .claude/commands/<name>.md, but the skills/ directory is the recommended approach.

Anatomy of a Skill

Each skill is a directory containing a SKILL.md file. The directory can also hold supporting files like reference docs, scripts, or examples.

.claude/skills/deploy/
├── SKILL.md
├── reference.md
└── scripts/
    └── check-env.sh

Frontmatter Reference

---
name: deploy
description: Deploy the application to the target environment
argument-hint: [target]
user-invocable: true
disable-model-invocation: false
allowed-tools: Read, Grep, Glob, Bash
model: opus
effort: high
context: fork
agent: Explore
---

Arguments and Variables

Skills support positional arguments and built-in variables.

---
name: fix-issue
description: Fix a GitHub issue by number
argument-hint: [issue-number]
---

Fix GitHub issue $ARGUMENTS following the project's coding standards.

Running /fix-issue 42 replaces $ARGUMENTS with 42.

For multiple arguments, use indexed access:

---
name: migrate
description: Migrate a component between frameworks
argument-hint: [component] [from] [to]
---

Migrate $0 from $1 to $2.

Running /migrate SearchBar React Vue fills in the values.

Available variables:

Dynamic Context with Shell Commands

Skills can inject live data using the !`command` syntax. The command runs before the prompt is sent to Claude, and its output replaces the placeholder.

---
name: pr-review
description: Review the current pull request
allowed-tools: Bash(gh *)
---

## Context

- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

## Task

Review this pull request for correctness, security, and style.

Supporting Files

Keep SKILL.md under 500 lines. Move detailed reference material to sibling files and link to them:

For API conventions, see [reference.md](reference.md).
Run the validation script: `python ${CLAUDE_SKILL_DIR}/scripts/validate.py`

Invocation

/deploy              # invoke with no arguments
/deploy production   # invoke with arguments

Claude can also invoke skills automatically based on conversation context, unless disable-model-invocation: true is set.

Full Example

---
name: bootstrap
description: |
  Repository-aware DevOps assistant. Inspects the repo, sets up CI,
  deployment configs, and secrets handling.
argument-hint: [target-platform]
user-invocable: true
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
---

You are a repository-aware DevOps, CI, and deployment assistant.

Your job is to inspect the repository, ask only the necessary questions,
and set up:

1. A local CI workflow for validating code before push
2. A clean Git commit + push workflow
3. A deployment workflow for the chosen platform
4. Proper handling of environment variables and secrets

Start by inspecting the repository.

OpenAI Codex

Codex CLI has a layered customization system. Skills are the primary mechanism for reusable workflows, replacing the older custom prompts system.

Where Skills Live

Codex walks up from the current directory to the repo root, discovering skills at each level. Skills closer to the working directory take precedence.

SKILL.md Format

The format follows the same open standard as other agents. Frontmatter requires name and description:

---
name: code-review
description: Perform a thorough code review on staged changes
---

Review all staged changes for:
1. Correctness and logic errors
2. Security vulnerabilities
3. Performance issues
4. Style consistency

Provide specific line references and suggested fixes.

A skill directory can also contain an agents/openai.yaml file to control UI appearance, implicit invocation behavior, and tool dependencies.

Invocation

$skill-name          # prefix with $ in prompts
/skills              # list available skills

Codex can also auto-select skills based on prompt context and the skill's description, unless disabled in configuration.

Project Instructions with AGENTS.md

Codex reads AGENTS.md files before doing any work. The discovery chain:

1. Global: ~/.codex/AGENTS.override.md or ~/.codex/AGENTS.md
2. Project: Walk from repo root to current directory, checking for AGENTS.override.md then AGENTS.md at each level

Files are concatenated root-down, so files closer to the working directory appear later and effectively override earlier guidance. Combined size limit is 32 KiB by default.

Custom Prompts (Deprecated)

The older system stored Markdown files in ~/.codex/prompts/. The filename became the slash command (e.g., review.md became /review). These still work but the docs recommend migrating to skills.

Custom prompts supported the same placeholder syntax: $1-$9, $ARGUMENTS, and named variables supplied as KEY=value pairs.

GitHub Copilot

Copilot has four layers of customization: custom instructions, prompt files, agent skills, and extensions. Skills availability varies by surface.

Custom Instructions

The foundation layer. Applied automatically to all Copilot requests in a repo.

Repository-wide: Create .github/copilot-instructions.md at the repo root:

# Copilot Instructions

- Use TypeScript strict mode
- Prefer functional components with hooks
- Follow the existing error handling patterns in src/lib/errors.ts

Path-specific: Store files in .github/instructions/ with glob-based targeting:

---
applyTo: "**/*.ts,**/*.tsx"
---

Use Zod for all input validation. Prefer branded types for domain IDs.

Personal: $HOME/.copilot/copilot-instructions.md for CLI, or VS Code settings for the IDE.

Priority order: Personal > Repository > Organization.

Copilot CLI also reads AGENTS.md, CLAUDE.md, and GEMINI.md at the repo root. When multiple instruction files exist, all are used.

Prompt Files (VS Code / IDE)

Reusable prompt files stored in .github/prompts/ with the .prompt.md extension. These work as custom slash commands in Copilot Chat within VS Code, Visual Studio, and JetBrains IDEs.

---
name: review-component
description: Review a React component for accessibility and performance
agent: agent
tools:
  - codebase
---

Review the selected component for:
1. Accessibility (ARIA labels, keyboard navigation, screen reader support)
2. Performance (unnecessary re-renders, missing memoization)
3. Error boundaries and loading states

Reference the project's component guidelines in docs/component-standards.md.

Frontmatter fields:

The body supports relative Markdown links to workspace files, tool references via #tool:<name>, and variables like ${selection} and ${input:variableName}.

Invocation: Type /prompt-name in Copilot Chat, use the Command Palette, or press the play button in the editor.

Important: Prompt files are not yet supported in the Copilot CLI. This is an active feature request.

Agent Skills (SKILL.md)

Copilot also supports the SKILL.md open standard, shared with Claude Code and Codex.

Storage:

The SKILL.md frontmatter requires name and description:

---
name: api-scaffold
description: Scaffold a new API endpoint following project conventions
---

Create a new API endpoint:
1. Add the route handler in src/app/api/
2. Define request/response types in src/types/
3. Add input validation with Zod
4. Include error handling following src/lib/errors.ts patterns
5. Add a basic test file

Invocation in Copilot CLI:

/skills list          # list available skills
/skills info <name>   # show skill details
/skill-name           # invoke directly

Copilot can auto-select skills based on context and description.

Platform support: GitHub Copilot coding agent, Copilot CLI, and VS Code Insiders (agent mode). VS Code stable support is coming.

Copilot Extensions

Extensions are a separate system for integrating third-party services into Copilot Chat. They are invoked with @extension-name syntax and are built as server-side integrations (typically using MCP), not local Markdown files. Extensions are distributed through the GitHub Marketplace.

Cross-Tool Comparison

All three tools are converging on the SKILL.md open standard. If you want maximum portability, use SKILL.md format and place skills in locations each tool can discover.

A Portable Skill Directory

If your team uses multiple AI agents, you can structure your skill directories so that each tool finds what it needs:

your-repo/
├── .claude/skills/          # Claude Code discovers these
│   └── deploy/SKILL.md
├── .agents/skills/          # Codex discovers these
│   └── deploy/SKILL.md
├── .github/
│   ├── skills/              # Copilot discovers these
│   │   └── deploy/SKILL.md
│   └── prompts/             # Copilot VS Code prompt files
│       └── deploy.prompt.md
├── AGENTS.md                # Read by Codex and Copilot CLI
└── CLAUDE.md                # Read by Claude Code

If your skills are identical across tools, you can symlink them to avoid duplication:

# Create the skill once
mkdir -p .claude/skills/deploy

# Symlink for other tools
mkdir -p .agents/skills .github/skills
ln -s ../../.claude/skills/deploy .agents/skills/deploy
ln -s ../../.claude/skills/deploy .github/skills/deploy

Writing Good Skills

A few principles that apply regardless of which agent you use:

Be Specific About the Task

Bad:

Help me deploy.

Good:

You are a deployment assistant for a Next.js application on Vercel.

1. Verify the build passes locally
2. Check that environment variables are set
3. Push to the deployment branch
4. Verify the deployment succeeded via the Vercel CLI

Include Constraints

Tell the agent what not to do. This prevents over-engineering and hallucinated steps.

Rules:
- Only include CI steps that the project actually supports
- Never fabricate test commands if no test framework is configured
- Do not modify existing CI configs without asking first

Structure as a Conversation Flow

For complex workflows, define the steps the agent should follow in order:

### Step 1: Inspect
Scan the repo for existing configs and summarize what you find.

### Step 2: Ask
Ask the user which platform they want to deploy to.

### Step 3: Configure
Generate the minimal config for that platform.

### Step 4: Verify
Run the build and report any issues.

Keep SKILL.md Under 500 Lines

Move reference material, examples, and detailed specs into supporting files. Link to them from SKILL.md.

Use Arguments for Flexibility

---
name: scaffold
argument-hint: [component-type] [name]
---

Create a new $0 named $1 following the project's conventions.

This lets one skill handle scaffold page Dashboard, scaffold component UserCard, etc.

Getting Started

The fastest way to start using skills:

1. Pick one agent you use daily
2. Identify a task you repeat often (code review, component scaffolding, deployment)
3. Write the instructions as a Markdown file with frontmatter
4. Save it in the correct skills directory for your agent
5. Invoke it with the slash command and iterate

Skills compound. Once you have a few that your team relies on, they become part of your development workflow, versioned and reviewed like any other code.