Agent Skills & Claude Skills: The Complete Guide to SKILL.md Architecture

What Are Agent Skills and Claude Skills?

An agent skill is a reusable, filesystem-based instruction package—anchored by a standardized SKILL.md entrypoint—that teaches an AI coding agent how to execute a specialized, multi-step workflow. Instead of pasting repeated setup prompts, rubrics, and formatting constraints into every chat session, an engineer packages the workflow once with explicit boundary criteria, input prerequisites, execution steps, and output schemas.

According to the official Anthropic Claude Code Documentation: “Skills are modular packages containing a SKILL.md file and optional supporting files that provide reusable instructions, scripts, and context to Claude Code.” Anthropic pioneered this pattern with Claude Skills in the Claude Code CLI, where placing a skill folder in your configuration instantly registers a slash command (such as /summarize-changes) while enabling automatic semantic triggering when a prompt matches the skill's description.

Similarly, the OpenAI Codex Agent Guide and Google Antigravity standardize on filesystem-based skills that encapsulate complex developer workflows.

Agent skills operate through an architectural separation between discovery and execution. During startup, the agent scans registered skill directories, reads lightweight metadata (30 to 50 tokens of YAML frontmatter per skill), and registers semantic trigger phrases or slash commands. The full procedural body and reference templates load into the context window only when the user invokes the skill or the agent's intent classifier detects a matching task.

The Anatomy of a Skill: What Goes Inside the Folder

Whether created for Claude Code, OpenAI Codex, or Google Antigravity, every agent skill lives as a dedicated folder containing a mandatory entrypoint and optional supporting assets:

How Do Agent Skills Differ From Prompts, Custom Instructions, and Tools?

Agent skills represent a distinct middle tier in AI architecture between disposable text prompts and programmatic software tools. While prompts are ephemeral single-turn requests and custom instructions define broad behavioral defaults, agent skills encapsulate complete, task-specific operational procedures with negative boundaries and output schema contracts. Tools execute deterministic external actions via APIs, whereas skills instruct the agent on how and when to orchestrate those tools effectively.

For an in-depth exploration of instruction scopes, read our comparative guides on skills vs prompts, custom instructions vs skills, Claude Skills vs MCP, and Cursor Rules vs Claude Skills & AGENTS.md.

When Should You Create a Skill vs Writing a Prompt?

Use this three-part heuristic to decide whether an instruction belongs in a chat prompt or a dedicated skill folder:

1. Frequency: Do you find yourself writing or pasting roughly the same instructions at least once a week? If yes, it belongs in a skill.
2. Complexity: Does the task require a multi-step checklist, an explicit output schema, or negative boundary constraints? If yes, it belongs in a skill.
3. Shared Value: Would another engineer on your team benefit from running this exact workflow without learning your personal prompt tricks? If yes, it belongs in a skill.

Claude Skills vs MCP: How Do Agent Skills and Tool Protocols Compare?

The fundamental difference between Claude Skills and the Model Context Protocol (MCP) is that skills define operational logic and procedural guardrails, while MCP establishes bi-directional external system connectivity. A Claude Skill teaches an agent how to parse diffs, enforce security checklists, or format pull request descriptions, whereas an MCP server gives that agent the capability to query live PostgreSQL databases, inspect GitHub API endpoints, or execute remote container commands.

As defined in the official Model Context Protocol Specification: “MCP is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools.” Operating over standard JSON-RPC 2.0 (via stdio or Server-Sent Events), MCP exposes stateful resources, prompt templates, and callable tool functions directly to the agent runtime.

Conversely, according to the Anthropic Claude Code Documentation: “Skills are modular packages containing a SKILL.md file and optional supporting files that provide reusable instructions, scripts, and context to Claude Code.” Skills reside in the local filesystem (such as ~/.claude/skills/) and load lazily based on YAML frontmatter triggers.

Comparative Matrix: Claude Skills (SKILL.md) vs Model Context Protocol (MCP)

Comparing lifecycle execution, token overhead, communication protocols, and primary failure modes highlights how skills and MCP complement each other across an AI agent stack:

How Do Claude Skills and MCP Servers Orchestrate Workflows Together?

High-performance AI agent workflows orchestrate skills and MCP in a layered pipeline where the skill provides the reasoning playbook and MCP provides the execution engine. Without a skill, an MCP-connected agent calls tools haphazardly without validation boundaries. Without MCP, a skill cannot access live production state.

Consider an automated incident triage workflow. The MCP server exposes tools like fetch_pagerduty_alert and post_slack_update, while the Claude Skill dictates the exact diagnosis sequence, severity calculation rubric, and communication protocols:

# File: ~/.claude/skills/incident-triage/SKILL.md
---
name: incident-triage
description: Diagnoses production incident alerts using connected MCP tools and formats executive escalation briefs.
---

# Incident Triage Playbook

## Tool Preconditions
1. Verify alert severity using `mcp__pagerduty_fetch_incident`.
2. Query error rate spikes over the last 15 minutes with `mcp__datadog_query_metrics`.
3. If error rates exceed 5.0%, invoke `mcp__sentry_get_issue_stacktrace`.

## Safety Constraints
- NEVER post to executive channels without user verification if alert status is SEV-3 or lower.
- Sanitize all PII and API keys from stack traces before generating incident logs.

## Output Contract
Return a markdown table containing: Incident ID, Root Cause Hypothesis, Impact Radius, and Action Items.

In this architecture, the skill acts as an intelligent guardrail. It prevents the agent from making premature API writes, enforces structured schemas, and ensures consistent quality before external actions occur. To build automated multi-agent pipelines around this pattern, see our walkthrough on building an MCP skill sync pipeline.

What Are the Token and Latency Economics of Skills vs MCP?

Token efficiency and execution latency differ significantly between skills and MCP servers. Registering ten MCP tools in a session adds between 1,500 and 3,000 static tokens to every single conversational turn because tool JSON schemas (parameters, descriptions, required properties) are injected into the system preamble.

By contrast, Claude Code skills utilize an on-demand filesystem architecture. At launch, the agent runtime scans available skill folders and builds an in-memory index requiring only 35 to 50 tokens per skill. The full instruction text is read into context only when triggered, yielding up to a 90% reduction in baseline context consumption.

Furthermore, local skill execution incurs zero network latency, whereas MCP remote tool calls over SSE or cloud proxies introduce 150ms to 600ms of round-trip network overhead per tool invocation. Designing workflows with lightweight local skills that trigger MCP tools only when strictly necessary optimizes both token cost and execution velocity.

What Is the SKILL.md Specification Inside an Agent Skill Directory?

The SKILL.md file is the structural backbone and standardized entrypoint of an AI agent skill directory. It fulfills two essential computational responsibilities: an indexing manifest that exposes metadata to the agent during initialization, and an operational playbook that guides model execution once the skill is triggered.

The top of every SKILL.md file must contain a YAML frontmatter block enclosed between opening and closing triple-dash delimiters (---). This metadata allows agent runtimes like Claude Code, OpenAI Codex, and Google Antigravity to index the skill without loading its full text into the active context window.

Because AI agents use semantic embeddings to match user tasks against skill descriptions, frontmatter description quality directly dictates triggering reliability:

Real-World Examples: From Minimal Git Diff Review to Modular API Auditor

A skill can be as simple as a single SKILL.md file with a dynamic shell execution command, or a multi-file package with templates and bash validators.

Example 1: Minimal Git Diff Review Skill (Single-File)

Below is a practical, lightweight skill you can drop directly into ~/.claude/skills/summarize-changes/SKILL.md. Notice how it uses the backtick-bang syntax (!`git diff HEAD`) to pull live git changes into context automatically:

---
description: Summarize uncommitted Git changes and flag risky edits. Use when the user asks what changed, wants a commit summary, or asks for a quick diff review.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in three bullets.
Then list any risks, missing tests, hardcoded values, or follow-up checks.
If there are no changes, say there are no uncommitted changes.

Because this folder is named summarize-changes, you can invoke it manually in Claude Code via /summarize-changes, or simply ask “what changed in my repo?” and Claude will automatically invoke the skill based on the frontmatter description.

Example 2: Production Multi-File Directory Pattern

A production-grade agent skill remains lightweight by delegating secondary reference materials, validation scripts, and templates into modular subdirectories:

api-reviewer/
|-- SKILL.md
|-- references/
|   |-- http-status-codes.md
|   `-- security-checklist.md
|-- templates/
|   `-- review-summary-template.md
`-- scripts/
    `-- validate-zod-schema.sh

Below is the corresponding SKILL.md demonstrating strict YAML frontmatter, boundary constraints, input prerequisites, execution phases, and an explicit output schema contract:

---
name: typescript-api-reviewer
description: Validates TypeScript Express and Next.js route handlers against production security, schema validation, and error-handling standards.
triggers:
  - "/review-api"
  - "review API route"
  - "audit route handler"
version: 1.2.0
author: Backend Engineering Team
---

# TypeScript API Route Reviewer

Use this skill when auditing TypeScript API handlers for security, error handling, and type safety.

## Boundary Conditions
- **DO NOT USE** for GraphQL resolvers or gRPC services.
- **DO NOT USE** for client-side React component data fetching hooks.

## Required Inputs
1. Target route file path (e.g. `app/api/users/route.ts`).
2. Associated Zod schema definitions.

## Execution Workflow
1. **Schema Validation:** Verify all incoming request bodies, headers, and query params parse through Zod schemas.
2. **Type Safety:** Ensure zero usage of `any` or untyped `Promise<unknown>`.
3. **Status Envelope:** Ensure error responses return uniform JSON: `{ error: { code: string, message: string } }`.
4. **Database Security:** Assert that all ORM/SQL queries use parameterized inputs.
5. **Reference Lookup:** If inspecting financial or auth endpoints, read `references/security-checklist.md`.

## Output Schema Contract
Provide review findings formatted into these exact markdown headers:
### 1. Critical Security Blockers
### 2. Type Safety & Schema Issues
### 3. Recommended Code Refactor (Full TypeScript Implementation)

For complex multi-file workflows that include golden examples and evaluation scripts, follow our comprehensive guide to multi-file Claude Skills. To generate initial drafts without manual YAML formatting, use our free Claude Skill Creator.

Why Does Lazy-Loaded SKILL.md Architecture Save Up to 96% Token Context?

The core economic and architectural advantage of the SKILL.md standard is lazy evaluation. In a mature software development environment, an engineer accumulates 15 to 30 specialized skills covering database migrations, API contracts, automated unit testing, security vulnerability scans, and release summaries.

• Monolithic Prompt Preambles: When all 20 skills are injected into system prompts or global instructions, they consume roughly 1,200 tokens each, creating an immediate context tax of 24,000 tokens on every conversation turn before any task code is loaded.
• Lazy-Loaded SKILL.md Architecture: Under the SKILL.md standard, Claude Code and OpenAI Codex parse only the 30- to 50-token YAML frontmatter during initialization. A library of 20 skills consumes only 700 to 1,000 tokens of indexing context.
• Context Bandwidth Savings: This architectural separation delivers an immediate 96.2% reduction in initial token overhead, preserving maximum context bandwidth for codebase ASTs, large git diffs, and complex multi-file edits.

The detailed instructions, schema contracts, and reference files load into the agent's context window only when the agent explicitly selects that skill for the active task.

How Do Different AI Agents Parse SKILL.md Frontmatter and Bodies?

Different AI agent runtimes handle skill directories with subtle variations in filesystem paths, metadata parsers, and trigger evaluation. Understanding these execution models ensures your skill library remains completely portable across your toolstack.

To explore how editor-specific rules interact with cross-agent skill packages, see our comparative guide on Claude skills vs Cursor rules, our breakdown of Claude skills across projects and directory scopes, and our guide on OpenAI Codex skills.

6 Steps to Get Started With Agent and Claude Skills

Transitioning your workflow from ad-hoc prompting to a clean skill library is straightforward if you follow a structured sequence:

1. Pick one repetitive task: Choose a workflow you run several times a week (e.g. reviewing a git diff, auditing an API route, writing PR release notes).
2. Name the skill by its outcome: Use a clear, lowercase, hyphenated slug like git-diff-reviewer or release-notes. Remember that in Claude Code, this folder name becomes your /slug command.
3. Write the description first: Focus on intent matching. State exactly what the skill does and what signals should trigger it. This is what the agent's router evaluates.
4. Draft deterministic execution instructions: Write clear step-by-step procedural steps, negative boundaries (what NOT to do), and an explicit output schema.
5. Test on real work: Execute the skill in Claude Code or Codex. Verify that the agent follows your formatting and catches subtle edge cases.
6. Save and synchronize: Keep the skill in your global skills directory (~/.claude/skills/) or sync it automatically across all machines using Prompttly.

The Sprawl Moment: When Skills and Prompts Drift Across Machines

An engineer writes a meticulous 180-line SKILL.md for TypeScript API route validation on their personal desktop. The skill defines strict Zod validation checks, status envelopes, and error boundaries. Two weeks later, they clone a new microservice repository on their work laptop. When they invoke their code reviewer, Claude Code falls back to generic formatting rules because the local skills folder is completely empty. In a hurry, they copy a partial snippet from Slack into a repo-level .claude/skills folder, but omit the YAML frontmatter delimiters. Claude Code fails to parse the file, ignores the custom rules entirely, and generates untyped Express handlers. The developer now has three diverging versions of the same skill across two laptops and a git branch, none of which stay synchronized.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

If you are experiencing prompt fragmentation across multiple assistants, read our guides on managing prompt sprawl across 3+ AI coding assistants, our architectural comparison of Codex skills vs Claude Code skills, and fixing broken AI agent instructions across repos and worktrees.

When Not to Create an Agent Skill

Not every prompt or developer preference should become an agent skill. Over-indexing on skills creates selection friction and increases the probability that an agent chooses an irrelevant instruction package. Maintain strict boundaries:

• One-off exploratory tasks: Keep exploratory queries as standard conversation prompts. Only convert a workflow into a skill once the task repeats across projects.
• Vague stylistic taste: Broad tone preferences belong in global custom instructions or agent profiles, not specialized skill files.
• Monolithic mega-skills: Avoid creating a single skill that attempts to handle database design, frontend styling, and deployment scripts simultaneously. Deconstruct workflows into focused, modular packages.
• Deterministic API integrations: If a task requires fetching live records, authenticating with third-party services, or executing shell scripts, build an MCP server instead and let the skill orchestrate the tool.

How Do You Build and Maintain a Portable Agent Skill Library?

Building a durable skill library requires treating agent instructions as version-controlled engineering assets rather than disposable chat prompts. High-performing engineering teams establish a single canonical source of truth, enforce strict semantic naming conventions, decouple personal preferences from shared project skills, and automate multi-machine synchronization.

1. Audit recurring workflows: Identify prompts, validation checklists, and instructions you paste repeatedly into AI assistants every week.
2. Establish one canonical source of truth: Avoid maintaining fragmented versions in personal notes, private git repos, and Slack threads.
3. Enforce semantic directory naming: Ensure the skill folder name exactly matches the name field in the SKILL.md YAML frontmatter.
4. Isolate personal from shared team skills: Keep individual writing preferences in personal folders (~/.claude/skills) while committing team-wide quality gates to project repositories.
5. Version behavior changes: When updating output schemas or boundary criteria, increment the version field and document breaking changes.
6. Sync directly to runtime targets: Ensure skills are mirrored automatically into the active configuration directories of Claude Code, Codex, and Cursor across all development laptops.

Agent Skill Production Readiness Checklist

1. Valid YAML Frontmatter: Opening and closing triple-dash delimiters (---) present; zero tabs or unescaped colons.
2. Matching Identifier Slug: The name field in YAML exactly matches the parent directory slug.
3. High-Signal Description: Concisely states the exact task, input prerequisites, and output format under 1,024 characters.
4. Explicit Negative Boundaries: Enumerates negative conditions detailing when the agent must not execute the skill.
5. Deterministic Output Schema: Defines strict headings, tables, or JSON structures that the model must return.
6. Relative File Links: All references to supporting templates or scripts use relative directory syntax (e.g. references/rules.md).
7. Cross-Machine Portability: Tested and verified across Claude Code, OpenAI Codex, Google Antigravity, and Prompttly sync.

Common Agent Skill and Frontmatter Mistakes to Avoid

Most skill failures happen silently. The agent still responds, but it executes generic training defaults rather than your customized workflow. Guard against these common failure patterns:

• Missing Frontmatter Delimiters: Omitting the opening or closing --- lines causes agents to treat YAML metadata as plain text, completely disabling semantic trigger detection.
• Overly Broad Trigger Keywords: Using generic descriptions like “helps with code” triggers the skill on every single programming prompt, diluting context.
• Hardcoded Absolute Paths: Specifying /Users/username/skills/helper breaks cross-machine sync. Always use relative paths for supporting files.
• Unversioned Schema Upgrades: Changing the output schema without bumping the version field breaks automated scripts and teammate workflows. See how to update skills safely.
• Monolithic File Bloat: Pasting 3,000 lines of API documentation inside SKILL.md wastes token context on every invocation. Split large docs into references/.
• Local-Only Storage: Keeping skills on a single machine guarantees loss or drift during hardware upgrades. See our guide on transferring settings to a new computer.

Frequently Asked Questions About Agent Skills and Claude Skills

Where to Go Next

Browse the resources hub for our complete collection of AI workflow architecture guides. To implement and manage skills across your development stack:

• How to Install and Use Claude Skills — Step-by-step authoring, installation, and slash command execution guide.
• Claude Skills Across Projects — Personal vs project directory scopes, resolution precedence, and monorepo setups.
• Codex Skills Guide — Managing and packaging skills for OpenAI Codex CLI and coding agents.
• Codex Skills vs Claude Code Skills — Architectural comparison of instruction models, context token economics, and cross-agent workflow sharing.
• Multi-File Claude Skills — Modular packaging with external references, templates, and scripts.
• Updating Claude Skills Safely — Semantic versioning, isolated staging, and instant rollback strategies.
• How to Sync Claude Skills Across Computers — Multi-machine synchronization across laptops and remote environments.
• How to Share Claude Skills With Your Team — Team-wide skill governance, centralized libraries, and rollout workflows.
• Claude Skills for Developers — Reusable skill packs for code review, testing, migrations, and debugging.
• Multi-Machine AI Skill Sync with MCP — Building an automated skill synchronization pipeline across Claude Code and Codex using Model Context Protocol.
• MCP Prompt Server Architecture — Serving dynamic, parameterized prompt templates and workflows across Claude Desktop, Cursor, and IDEs.
• AI Agent Skill Marketplaces and Registries — Where to find, evaluate, and share community skills, MCP registries, and tool directories.
• Claude Skills Troubleshooting Guide — Debugging YAML syntax errors, trigger mismatches, and execution bugs.

When you are ready to eliminate manual file copying and manage your skills across every machine and AI agent, explore Prompttly individual and team plans or download the Prompttly Mac app.