AI Agent Skills Guide 2026: SKILL.md, Claude Code, Codex & Security

This updated guide reframes AI Agent Skills Guide 2026: SKILL.md, Claude Code, Codex & Security around practical search intent: what readers need to compare, choose, install, secure, or operationalize in 2026. It focuses on decision criteria, workflow fit, and the trade-offs that matter once an AI agent, skill, marketplace, or automation moves from curiosity to daily use.

The article also broadens the semantic coverage around SKILL.md, AI agent skills, agent instructions. That gives readers a clearer path from high-level research to implementation planning, while keeping the content useful for teams evaluating AI agent skill design.

Quick Answer

A useful skill is narrow, repeatable, and explicit about inputs, tools, constraints, and success criteria, so the agent can act consistently instead of guessing.

Table of Contents

• What Are AI Agent Skills?
• How Skills Work: Progressive Disclosure
• The SKILL.md File Format
• Skills Across Platforms: A Comparison
• How to Create Your First Skill
• Real-World Skill Example: CSV Analyzer
• Installing and Sharing Skills
• The Agent Skills Open Specification
• Security and Safety: Treating Skills Like Code
• Best Practices for Writing Effective Skills
• Key Takeaways

**Focused reference series:**This page is the broad hub. For the highest-detail answer on the manifest itself, use SKILL.md Format & Manifest Spec. For platform-specific differences, use Claude Code Skills vs OpenAI Codex Skills. For persistent repo instructions versus on-demand skills, use SKILL.md vs AGENTS.md.

What Are AI Agent Skills?

If you've ever found yourself pasting the same long instructions into ChatGPT, Claude, or Codex at the start of every session—explaining your project's conventions, how to run tests, or how deployments work—skills solve that problem permanently.

An AI agent skill is a reusable instruction bundle that teaches an AI coding assistant a specific procedure. Think of it as a recipe card for your agent: it describes when to activate, what to do, and how to do it. The skill lives in a folder in your project or on your system, and the agent loads it automatically when it's relevant.

At its core, a skill is a folder whose centerpiece is a SKILL.md file. That file contains two parts:

YAML frontmatterwith metadata (name, description) used for discovery and routingA Markdown bodywith step-by-step instructions the agent follows when the skill activates

The folder can also include scripts/

, references/

, and assets/

directories with supporting files the agent can read or execute on demand.

**Want to skip writing from scratch?**Browse our AI Agent Skills Database — a curated library of 2,636+ ready-to-use SKILL.md files for Claude Code, Codex, OpenAI, and more. Download, customize, and drop them straight into your project.

**Skills vs. system prompts vs. tools:**System prompts set global constraints. Tools perform side effects (file I/O, API calls). Skills package

repeatable proceduresplus scripts and assets so they can be versioned, shared, and reused independently—like functions for your AI assistant.

How Skills Work: Progressive Disclosure

Skills don't dump their entire contents into the AI's context window from the start. That would waste tokens and slow things down. Instead, every major platform uses a three-tier progressive disclosure model:

The Skill Lifecycle

**Catalog disclosure:**At session start, the agent sees only each skill'sname

anddescription

—a compact list that costs minimal tokens. This is enough for the agent to know what's available.**Activation:**When the agent determines a skill is relevant (either because you triggered it or because the task matches the description), it loads the full SKILL.md body into context.**Resource loading:**Scripts, reference documents, and assets are loaded on-demand only when the instructions reference them—not preemptively.

This design keeps context lean. A project with 20 installed skills might only pay the token cost for 1–2 of them in any given session.

The SKILL.md File Format

The SKILL.md file is the manifest that makes everything work. Here's the anatomy of one:

For a field-by-field reference with copyable templates, versioning guidance, and platform notes, see the dedicated guide: SKILL.md Format & Manifest Spec. If you are deciding between a skill and persistent Codex instructions, use SKILL.md vs AGENTS.md.

Required Frontmatter Fields

(required): 1–64 characters, kebab-case (name

a-z

, numbers, hyphens). Must match the parent directory name. No consecutive hyphens.(required): 1–1024 characters. Explains what the skill doesdescription

andwhen to use it. This is the routing signal—make it keyword-rich.

Optional Frontmatter Fields

: License identifier (e.g., MIT, Apache-2.0).license

: Runtime requirements (binaries, network, OS).compatibility

: Additional key-value pairs for platform-specific properties.metadata

(experimental): Space-delimited allowlist of tools the skill may use.allowed-tools

**Pro tip:**The description field is the single most important thing you write. It drives both implicit activation (the agent auto-selects) and search/discovery. Include the actual phrases your team uses—"deploy to staging", "push to prod", "run the migration"—not just technical descriptions.

Skills Across Platforms: A Comparison

The SKILL.md format has been adopted across multiple AI coding platforms, but each implements it differently. Here's how they compare:

For a deeper source-backed table covering paths, invocation syntax, agents/openai.yaml

, CLAUDE.md

, and AGENTS.md

, see the dedicated comparison: Claude Code Skills vs OpenAI Codex Skills.

Claude Code

Anthropic's CLI agent. Skills live in your project's .claude/skills/

directory or the user-level ~/.claude/skills/

. Skills can be invoked as slash commands (e.g., /deploy

) or triggered automatically when the agent recognizes a matching task from the description.

OpenAI Codex

OpenAI's coding agent. Scans .agents/skills/

up the directory tree to the repo root, plus user-level ~/.agents/skills

and admin /etc/codex/skills

. Supports an optional agents/openai.yaml

sidecar for UI metadata and MCP tool dependencies.

OpenClaw

Open-source agent with a skill registry (ClawHub). Loads from bundled, managed (~/.openclaw/skills

), and workspace sources with configurable precedence. Supports load-time gating (OS, binaries, env vars) and per-run environment injection.

Claude Web (claude.ai)

Claude.ai has built-in Agent Skills (PowerPoint, Excel, Word, PDF) that activate automatically. Pro/Max/Team/Enterprise users can also upload custom skills as zip files via Settings. Separate from skills, Projects provide persistent instructions and knowledge files across conversations.

Claude Code Skills

Claude Code is Anthropic's terminal-based AI coding agent and has the most feature-rich skill implementation of any platform. Skills follow the Agent Skills standard with several powerful Claude-specific extensions.

Skill Scopes

Extended Frontmatter (Claude Code-specific)

Claude Code supports several frontmatter fields beyond the base Agent Skills spec:

Claude Code also supports dynamic context injection with !

commandsyntax (shell commands that run before the skill loads) and

argument substitution with $ARGUMENTS

, $1

, $2

, etc.

Built-in Skills

Claude Code ships with several skills out of the box:

/batch <instruction>

— parallel codebase changes across git worktrees/claude-api

— loads Claude API reference for your language/debug [description]

— troubleshoot sessions/loop [interval] <prompt>

— repeat a prompt on a schedule/simplify [focus]

— parallel code review and cleanup

**Legacy compatibility:**If you have old

.claude/commands/

files, they still work. Skills and commands share the same frontmatter format, but skills take precedence if both exist with the same name.

OpenAI Codex Skills

Codex uses the .agents/skills/

directory convention and supports both implicit and explicit skill invocation:

**Implicit invocation:Codex reads the description and automatically activates the skill when it detects a matching task—no slash command neededExplicit invocation:**Users type$skill-name

to force-activate a specific skill**Directory scanning:**Codex walks up the directory tree from your current working directory to the repo root, scanning every.agents/skills/

it finds. This means a monorepo can have global skills at the root and sub-project skills in nested directories**Sidecar metadata:**An optionalagents/openai.yaml

file can declare UI display names, invocation policies, and MCP tool dependencies

OpenClaw Skills

OpenClaw is an open-source AI agent that adds several unique capabilities on top of the baseline Agent Skills spec:

**Load-time gating:**Skills can declare prerequisites viametadata.openclaw

—required binaries, environment variables, OS, or config values. Skills that don't pass the gate aren't even shown to the model**ClawHub registry:A public skill registry where you can browse, install, and publish skills. Think npm for AI agent skillsThree-source precedence:**Bundled skills (shipped with OpenClaw) → managed skills (~/.openclaw/skills

) → workspace skills. Workspace skills override managed, which override bundled**Slash commands:**Skills can be markeduser-invocable: true

and given a custom slash command name**Environment injection:**OpenClaw can inject API keys and environment variables for the duration of a skill's execution, then restore the original environment afterward

**ClawHub safety note:**There have been reported incidents of malicious skills distributed through open registries like ClawHub. Always review skill contents before installing, especially any bundled scripts. Treat skills from unknown authors like untrusted npm packages.

Claude Web Interface (claude.ai)

Claude's web interface actually has two separate skill-like systems: built-in Agent Skills and Projects.

Built-in Agent Skills

Claude.ai comes with pre-built skills that activate automatically when you create documents:

PowerPoint (pptx)— create and edit presentationsExcel (xlsx)— create spreadsheets, data analysis, chartsWord (docx)— create and edit documentsPDF (pdf)— generate formatted PDFs

These work behind the scenes—no setup required. When you ask Claude to "make a slide deck" or "create a spreadsheet," the relevant skill activates automatically.

Custom Skills on claude.ai

On Pro, Max, Team, and Enterprise plans with code execution enabled, you can upload custom skills as zip files through Settings > Features. These skills run in a VM environment where Claude has filesystem access. Note that custom skills are individual to each user and do not sync across surfaces (claude.ai, API, and Claude Code are separate).

Projects (Separate Feature)

Projects on claude.ai provide conversation-level context—custom instructions and knowledge files that persist across chats within a project. This is a different feature from Skills, but serves a complementary purpose:

**Create a Project:From the Claude sidebar, create a new Project and give it a nameAdd Custom Instructions:Write instructions that persist across every conversation in the projectUpload Reference Files:**Attach documents, code samples, or data files that Claude can reference

Think of it this way: Projects provide context (who you are, what you're working on), while Skills provide capabilities (procedures the agent can execute).

Quick Comparison Table

How to Create Your First Skill

Let's walk through creating a skill from scratch. This example works on any Agent Skills-compatible platform—just adjust the directory path.

Create the Skill Directory

Make a folder for your skill. The folder name should match the skill's name

field.

Write the SKILL.md File

Create SKILL.md

inside your skill folder with frontmatter and instructions:

Add Supporting Files (Optional)

If your skill needs scripts or reference docs, add them to subdirectories:

Test It

Start a new session with your agent and try triggering the skill:

**Implicit:Just say "run the tests" and see if the agent activates your skillExplicit:**Use the platform's invocation syntax (/run-tests

in Claude Code,$run-tests

in Codex)

If the skill doesn't trigger, refine the description

field—it's almost always a routing problem.

Real-World Skill Example: CSV Analyzer

Here's a more substantial skill that bundles a Python script and a reference template. This demonstrates how skills handle multi-step workflows with validation gates:

This skill follows the "plan-validate-execute" pattern recommended by the Agent Skills specification. The agent won't blindly run the script—it validates inputs first, checks outputs after, and has a clear error-handling path.

Installing and Sharing Skills

Skills are just folders with files, so sharing them is straightforward:

Sharing via Git

The simplest approach: commit your .claude/skills/

or .agents/skills/

directory to your repository. Every team member who clones the repo gets the skills automatically. This is the recommended approach for project-specific skills.

User-Level Skills

For personal skills you want across all projects, place them in the user-level directory:

• Claude Code: ~/.claude/skills/

• Codex: ~/.agents/skills/

• OpenClaw: ~/.openclaw/skills/

Registry Installation (OpenClaw)

OpenClaw's ClawHub provides a public registry where you can browse and install community skills. It works similarly to npm: search, review, install, and pin versions. Codex also has built-in installer commands for skills.

Pre-Built Skill Libraries

If you don't want to write skills from scratch, our AI Agent Skills Database has over 2,636 curated SKILL.md files ready to download for Claude Code, Codex, OpenAI, and other platforms. Just download, drop into your skills directory, and you're good to go.

OpenAI Codex and API Skills

OpenAI Codex uses SKILL.md

skill folders and optional agents/openai.yaml

metadata. For API-level skill resources and upload constraints, use the current OpenAI developer documentation because endpoint limits and packaging rules can change.

**Portability tip:**If you want a skill to work on both Claude Code

andCodex, you can symlink the same skill folder into both

.claude/skills/

and .agents/skills/

. The SKILL.md format is identical.

The Agent Skills Open Specification

The Agent Skills specification (agentskills.io), originally developed by Anthropic, is the open format behind portable SKILL.md

files. Claude Code documents its skills as following the open standard, and OpenAI Codex documents skills as building on the open Agent Skills standard.

The spec defines:

Required frontmatter:name

anddescription

with specific validation rulesOptional frontmatter:license

,compatibility

,metadata

,allowed-tools

Folder conventions:scripts/

,references/

,assets/

**Naming rules:kebab-case, 1–64 characters, no consecutive hyphens, no leading/trailing hyphensValidation tooling:**A reference library (skills-ref

) for validating skill directories and generating prompt blocks**Discovery paths:**platform-specific locations such as Claude Code's.claude/skills/

and OpenAI Codex's.agents/skills/

If you keep the portable core clean—name

, description

, Markdown instructions, and standard optional fields—the same skill is easier to adapt across compatible agents. Put client-specific behavior in optional metadata or sidecar files so one platform's extension does not become another platform's parsing problem.

**Primary references:**Use the Agent Skills specification for the portable file format, the Claude Code skills docs for Claude-specific extensions, and the OpenAI Codex skills docs for Codex-specific paths and

agents/openai.yaml

. The spec also provides an implementor guide with guidance on:

• How to discover skills (scan project + user scopes)
• How to parse frontmatter (handle malformed YAML gracefully)
• How to manage context (prevent skill instructions from being pruned during long sessions)
• How to handle trust (gate project-level skills in untrusted repositories)

Security and Safety: Treating Skills Like Code

This is the section most people skip. Don't.

Skills are privileged instructions with real security implications. When an agent loads a skill, it follows those instructions with the same trust it gives system prompts. A malicious skill can:

• Exfiltrate data through prompt injection (asking the agent to send file contents to external services)
• Execute arbitrary code via bundled scripts
• Exhaust tokens and inflate costs (documented in academic research as "Clawdrain" attacks)
• Bypass tool restrictions by instructing the agent to use terminal commands instead of gated tools

**Real incidents have occurred.**Malware has been distributed through open skill registries. A 1Password analysis showed that malicious skills can bypass tool-gating assumptions by social-engineering agents into running terminal commands. Academic research has demonstrated Trojanized skills that cause multi-turn token exhaustion.

Your Security Checklist

**Review before installing:**Read the SKILL.md and every bundled script before adding a skill from an external source. Treat it like reviewing a pull request.**Pin versions:**If using a registry, pin to specific versions rather than trackinglatest

.**Trust boundaries:**Don't auto-load project-level skills from freshly cloned repositories without reviewing them first. Some platforms gate this automatically.**Minimize privileges:**Useallowed-tools

where supported to restrict what the agent can do during skill execution.**Approval gates:**Design skills with explicit confirmation steps before destructive actions (deleting files, deploying, sending messages).**Keep scripts minimal:**Bundled scripts should be short, readable, non-interactive, and have no network calls unless absolutely necessary.

Practical Best Practices for Writing Effective Skills

After studying how skills work across platforms and reading the Agent Skills authoring guidance, here are the patterns that consistently produce the best results:

Write for Your Agent, Not for Humans

Skills are instructions for an AI, not documentation for developers. Be imperative: "Run npm test

" rather than "The test suite can be executed via npm." Include explicit defaults: "If the user doesn't specify a branch, use main

." Don't offer menus of options—make the decision and let the user override.

Include Negative Triggers

Always define when the skill should not activate. Without this, you'll get false triggers that frustrate users. A good "When to use" section has both positive and negative examples:

Keep the Body Under 5,000 Tokens

The entire SKILL.md body loads into context on activation. If it's too long, it wastes context window space and may cause the agent to miss important parts. Move detailed reference material into references/

files and link to them from the body.

Design Scripts for Agents

If your skill bundles scripts, design them for non-interactive use:

• Accept all inputs as command-line arguments (no interactive prompts)
• Include a --help

flag with clear usage information - Output structured data (JSON) where possible

• Return meaningful exit codes and error messages
• Default to safe behavior (dry-run mode for destructive operations)

Test With Eval Prompts

The Agent Skills spec recommends building a set of test prompts: at least 5–10 that should trigger the skill and 3–5 that should not. Run "with skill" vs. "without skill" baselines to measure whether the skill actually helps. Track token usage if your platform exposes it.

Version and Iterate

Skills aren't write-once. As your project evolves, update the skill. When your deployment process changes, update the deploy skill. When your team adopts a new testing framework, update the test skill. Treat skill maintenance like code maintenance.

Key Takeaways

Skills are reusable instruction bundlesthat teach AI agents specific procedures. They live in SKILL.md files with YAML frontmatter (name + description) and a Markdown body with step-by-step instructions.**Progressive disclosure keeps things efficient:**agents see only skill names and descriptions at startup, loading full instructions only when a skill is relevant.**The format works across platforms:**Claude Code, Codex, OpenClaw, and the OpenAI Skills tool all use compatible SKILL.md files. The Agent Skills specification provides the cross-platform standard.**The description field is everything:**it drives both automatic activation and discovery. Write it like a search query with real trigger phrases your team uses.**Treat skills like code dependencies:**review before installing, pin versions, gate trust, and design with safety constraints. Real supply-chain attacks have already happened.**Start simple:**your first skill can be 10 lines of Markdown. You don't need scripts, assets, or complex workflows to get value from skills. A "run tests" or "deploy to staging" skill with 5 clear steps will save your team hours. Or browse 2,636+ ready-made skills in our AI Agent Skills Database.**Even web users benefit:**Claude's Projects feature provides the same core value—persistent instructions across conversations—without requiring the CLI or SKILL.md files.

The shift happening in 2026 is clear: we're moving from one-shot prompting to persistent, composable agent behaviors. Skills are how you get there. Whether you're using Claude Code, Codex, or OpenClaw, the investment in writing good skills pays for itself in the first week—and compounds from there.

Related Reading

• MCP Security: Risks and Best Practices 2026 Guide
• OpenClaw Security Risks: Skills, Exposure and Exploits 2026 Guide
• OpenClaw's 230+ Malicious Skills: Agentic AI Supply Chain Lessons