AI Agent Skill Development Tutorial: How to Build Skills That Actually Work

An AI agent skill is a folder of instructions and resources that teaches an AI agent how to perform a specific task reliably. Rather than repeating context in every conversation, you package your expertise once into a SKILL.md file, and the agent loads it automatically when needed. This tutorial walks through the complete process of building agent skills from scratch, with real examples you can use today.

What Is an AI Agent Skill?

An agent skill is a self-contained unit of capability that extends what an AI coding agent can do. Think of it like an onboarding guide for a new team member. Instead of re-explaining your workflows and preferences in every conversation, you package them once into a standardized format that the agent picks up automatically.

The Agent Skills format was introduced by Anthropic in 2025 and published as an open standard at agentskills.io in December 2025. It is now supported across Claude Code, OpenAI Codex, OpenClaw, Gemini CLI, GitHub Copilot, Cursor, and many other platforms. A skill you write today works across multiple agents with minimal changes.

How Is a Skill Different from a Plugin?

A skill is not a plugin. A plugin is code that adds a new API endpoint or integration. A skill is instructions and context that guide how an agent behaves. Skills can include executable scripts, but the core of a skill is always the instructions in the SKILL.md file.

What Does a Skill Folder Look Like?

At its simplest, a skill is a directory with a single file:

my-skill/
  SKILL.md          # Required: instructions and metadata
  scripts/          # Optional: executable code
  references/       # Optional: documentation loaded on demand
  assets/           # Optional: templates and resources

The only required file is SKILL.md. Everything else is optional but becomes important as skills grow in complexity.

How Do Agent Skills Work Under the Hood?

Agent skills use a design principle called progressive disclosure. Content is loaded in three stages, and only as much as needed enters the agent's context window.

Level 1: Metadata (always loaded, about 100 tokens per skill)

When a session starts, the agent reads only the name and description from every installed skill's YAML frontmatter. This compact listing goes into the system prompt so the agent knows what skills exist and when to use them. You can install many skills with almost no context penalty.

Level 2: Instructions (loaded when triggered, under 5k tokens)

When the agent decides a skill is relevant to the current task, it reads the full body of SKILL.md into context. Only at this point do your actual instructions get loaded.

Level 3: Referenced files and scripts (loaded on demand)

If the skill body references other files (like a style guide or API reference), the agent reads those only when it needs them. Scripts can be executed without being read into context at all. This is what makes skills scalable: the token cost at idle is zero regardless of how much content you bundle.

How to Write the SKILL.md File

Every skill starts with YAML frontmatter. The two required fields are name and description.

---
name: readme-writer
description: Creates professional README.md files for software projects.
  Use when the user asks to "write a README", "create a readme",
  "document this project", or "generate project documentation".
---

# README Writer

[Full instructions go here...]

What Is the Most Common Mistake When Writing Skills?

The most common mistake is writing a bad description. The description field is not for humans. It is the trigger condition the agent uses to decide whether to activate your skill.

A bad description looks like this: "Helps with documents." The agent has no idea when to use it.

A good description includes what the skill does and when to use it, with specific trigger phrases: "Creates professional README.md files. Use when the user asks to write a README, create a readme, document this project, or generate project documentation."

What Are the Frontmatter Rules?

The agentskills.io specification defines these constraints for the YAML frontmatter:

• name: lowercase letters, numbers, and hyphens only, max 64 characters, must not start or end with a hyphen, no consecutive hyphens
• description: max 1024 characters, must describe both what the skill does and when to use it
• The file must be named exactly SKILL.md, case-sensitive
• Avoid XML angle brackets (< or >) in frontmatter as they can inject unintended instructions into the system prompt

You can also add optional fields: allowed-tools, metadata, license, and compatibility.

Where Do You Save Agent Skills?

Each platform loads skills from specific locations. The location defines the scope.

When two skills share the same name, the higher-precedence location wins. A project-level skill overrides a personal one with the same name.

How Do You Invoke a Skill?

There are two ways to activate a skill:

• Implicit invocation: The agent automatically activates the skill when your request matches the skill's description. This is the behavior that makes skills feel natural.
• Explicit invocation: You call the skill directly. In Claude Code, use /skill-name. In Codex CLI, use $skill-name or the /skills selector.

Both platforms support both modes. A well-written description is what makes implicit invocation work reliably.

How to Build Your First Skill: A README Writer

Let us build a practical skill from scratch. This skill teaches the agent your preferred README structure and writes the file to disk automatically.

Step 1: Create the folder

mkdir -p ~/.claude/skills/readme-writer

Step 2: Write the SKILL.md file

---
name: readme-writer
description: Creates professional README.md files for software projects.
  Use when user asks to "write a README", "create a readme",
  "document this project", "generate project documentation",
  or "help me write a README.md". Works from a project description,
  existing code, or both.
---

# README Writer

## Overview

Generate a complete, professional README.md file and write it to disk.
The output should be clear enough for a first-time contributor.

## Step 1: Gather project context

Look for context in the codebase before asking the user. Check for
package.json, pyproject.toml, go.mod, LICENSE files, and .env.example.

Gather:
- What does this project do?
- What language and frameworks does it use?
- How do you install and run it?
- Are there environment variables needed?
- Is there a LICENSE file?

## Step 2: Write the README

Use this structure. Only include relevant sections:

# Project Name

One clear sentence describing what this project does.

## Features
- Feature one (be specific)
- Feature two

## Prerequisites
List what needs to be installed.

## Installation
Step-by-step setup with copy-pasteable commands.

## Configuration
If the project needs environment variables, show an example.

## Usage
Show the most common use case first.

## License

## Step 3: Write the file to disk

Once the content is ready, write it using:

cat > README.md << 'EOF'
[full content]
EOF

## Step 4: Quality check

Before finishing, verify:
- No placeholder text remains
- Every command in Installation is accurate
- Prerequisites match what the project actually needs
- License matches the LICENSE file if one exists

Step 3: Test the skill

Go to any project folder and ask your agent: "Can you write a README for this project?" The agent will inspect the codebase, write the README, and save it as README.md.

How to Build a Skill with Multiple Files

When your SKILL.md gets too long, split the detailed content into separate files. The agent loads them only when needed.

code-reviewer/
  SKILL.md
  references/
    criteria.md
    error-handling.md

The SKILL.md references these files using relative paths: "For detailed review criteria, see references/criteria.md." The agent reads them at Level 3, only during an active review session.

How to Use the allowed-tools Field

The allowed-tools frontmatter field restricts which tools the agent can call when a skill is active. This is useful for read-only skills where you do not want the agent writing files or executing commands.

---
name: log-analyzer
description: Analyzes application log files to identify errors and patterns.
  Use when user says "check the logs" or "analyze this log file".
allowed-tools: Read, Grep, Glob
---

With this active, the agent can only read and search files. It cannot execute shell commands or make external calls.

What Are the Design Principles for Great Agent Skills?

Single Responsibility

One skill, one job. A weather skill should not handle calendar events. If you are tempted to add unrelated functionality, make a separate skill.

Be Specific About When to Use and When Not to Use

Tell the agent when NOT to use a skill. This is just as important as telling it when to use one. It prevents the agent from activating the wrong skill for a task.

Use Imperative Instructions

Write clear, step-by-step instructions with explicit inputs and outputs. The agent follows these instructions like a runbook.

Keep the Description Tight

Front-load the key use case and trigger words. As noted in the OpenAI Codex documentation, Codex shortens skill descriptions when many skills are installed. Put the most important trigger phrases first.

Prefer Instructions over Scripts

Use executable scripts only when you need deterministic behavior or external tooling. Instructions are more flexible and easier to maintain.

How to Debug a Skill That Does Not Trigger

If your skill is not activating, follow these steps:

1. Check your description: Add more specific trigger phrases that match how users actually phrase requests.
2. Check your file path: Verify the skill is in the correct directory for your platform.
3. Check YAML syntax: Invalid YAML silently prevents loading. Frontmatter must start on line 1 with --- and end with ---.
4. Restart the session: Skills are snapshotted at session start. Edits made during a running session require a restart.
5. Test with explicit invocation: Use "/skill-name" or "$skill-name" directly. If it works explicitly but not automatically, the description needs better trigger phrases.
6. Run in debug mode: Claude Code supports claude --debug for verbose logging.

What Are the Security Risks of Agent Skills?

Skills can bundle executable code and instructions that control agent behavior. That same power makes malicious skills dangerous.

According to Anthropic's engineering blog and security researchers at Cisco and Snyk, malicious skills can exfiltrate data via prompt injection, steal credentials, or execute unauthorized actions.

Follow these security rules:

• Install skills only from trusted sources (official repos or your own team)
• Read every file in a skill folder before installing, especially files in scripts/
• Pay attention to instructions that tell the agent to make outbound network calls
• Never install a skill that asks you to paste secrets into chat
• Prefer skills from official repositories: github.com/anthropics/skills or github.com/openai/skills

How Do You Share Skills with Your Team?

The cleanest approach is to commit project skills to your repository:

mkdir -p .claude/skills/readme-writer
# add SKILL.md, then:
git add .claude/skills/
git commit -m "Add readme-writer skill for team"
git push

When teammates pull the repository, the skill is immediately available with no separate installation step. In Codex, the equivalent path is .codex/skills/ or .agents/skills/.

What Platforms Support Agent Skills?

The Agent Skills open standard has been adopted by dozens of tools. According to agentskills.io, supported platforms include:

• Claude Code and Claude.ai
• OpenAI Codex
• GitHub Copilot and VS Code
• Gemini CLI
• Cursor
• JetBrains Junie
• OpenClaw
• OpenCode
• Roo Code
• Tabnine
• Factory
• And many more

Skills you write today are portable across all these platforms. That portability makes the format worth investing in.

Frequently Asked Questions

Can skills communicate with each other or call other skills?

Yes. The agent can recognize when multiple skills are needed and chain them together. You can reference other skills in the SKILL.md instructions. According to the DigitalOcean tutorial on agent skills, skill chaining is supported but requires the agent to recognize when multiple skills apply to a single task.

How do I handle API keys and authentication in skills?

Never hardcode credentials in skill files. Use environment variables or a secure secrets manager. The SKILL.md should instruct the agent to read credentials from environment variables, not store them inline. As the DEV Community guide notes, skills that handle sensitive data should include clear security instructions in their manifest.

Can I build skills that work without an internet connection?

Yes. Skills are local folders on your machine. The SKILL.md file, reference documents, and scripts all live on your filesystem. No internet connection is needed to load or execute them. External API calls would require connectivity, but the skill definition itself is fully offline.

How many skills can I install without slowing down my agent?

Because of progressive disclosure, you can install many skills with minimal context penalty. Each skill adds only about 100 tokens at startup (just name and description). As noted in the OpenAI Codex documentation, the initial skills list is capped at roughly 2% of the model's context window. For very large skill sets, descriptions may be shortened, so front-load your trigger phrases.

Agent skills are the standard way to extend AI coding agents with reusable expertise. The three-level loading system is the core concept: Level 1 is your trigger, Level 2 is your runbook, and Level 3 is your reference library. Start with a simple skill like the README writer, get it working end-to-end, then add complexity by splitting content across files and adding executable scripts.

The SKILL.md format is an open standard, portable across Claude Code, OpenAI Codex, and dozens of other platforms. Skills you write today will work across multiple agents with minimal changes. The official skills repositories at github.com/anthropics/skills and github.com/openai/skills are good places to study well-written examples.