Creating Agent Skills: Reusable Instructions for AI Coding Assistants

Introduction

If you've ever found yourself repeatedly explaining the same project conventions, coding patterns, or workflows to your AI coding assistant, you've encountered the limitation of context-less AI interactions. Each conversation starts fresh, and all that hard-won domain knowledge evaporates.

Agent Skills solve this problem by providing a standardized format for packaging reusable instructions that AI assistants can load on demand. Think of them as "plugins" for your AI—domain-specific knowledge modules that activate when relevant and stay dormant when not needed.

In this guide, you'll learn how to create your own Agent Skills using the SKILL.md format specification. Whether you want to teach your AI assistant how to write blog posts in your project's style, handle specific deployment workflows, or follow your team's code review conventions, Agent Skills provide the structure to make that knowledge persistent and shareable.

Quick Start

If you just want to create a working skill immediately:

# Create skill directory structure
mkdir -p .github/skills/my-skill

# Create the SKILL.md file
cat > .github/skills/my-skill/SKILL.md <<'EOF'
---
name: my-skill
description: Describe what this skill does and when to use it. Use when the user asks about X or wants to do Y.
---

# My Skill

Instructions for the AI assistant go here in Markdown format.

## When to Use
- Specific trigger conditions
- Types of user requests this handles

## Workflow
1. First step
2. Second step
3. Third step
EOF
  

That's it! The AI assistant will now load these instructions when relevant to the user's request.

Prerequisites

• A project repository where you want to add skills
• Basic familiarity with YAML and Markdown syntax
• An AI coding assistant that supports Agent Skills (e.g., GitHub Copilot, Claude Code)

Problem Statement

AI coding assistants are powerful but stateless. Every conversation starts without knowledge of your specific project conventions, workflows, or domain expertise. This creates several challenges:

• Repetitive explanations: You explain the same patterns and conventions repeatedly
• Inconsistent outputs: Without context, the AI may produce code that doesn't match your project style
• Lost institutional knowledge: Complex workflows that team members know can't be easily transferred to AI
• Context overload: Loading all instructions at once wastes tokens and slows responses

Agent Skills address these challenges by providing a structured way to define instructions that load only when relevant, keeping interactions efficient while ensuring the AI has the context it needs.

Directory Structure

An Agent Skill lives in its own directory with a specific structure:

skill-name/
├── SKILL.md          # Required: Main instructions
├── scripts/          # Optional: Executable code
├── references/       # Optional: Additional documentation
└── assets/           # Optional: Templates, images, data files
  

The SKILL.md file is the only required component. The optional directories provide a place for supporting materials that the skill instructions can reference.

Directory Placement

Skills are typically placed in one of these locations:

• .github/skills/ — Recommended for GitHub Copilot and VS Code
• .claude/skills/ — Claude Code (also recognized by GitHub Copilot)

User-wide skill locations vary by tool; consult your AI assistant's documentation for details.

SKILL.md Format

The SKILL.md file combines YAML frontmatter with Markdown instructions. Here's the complete format:

Required Frontmatter

---
name: skill-name
description: What this skill does and when to use it.
---
  

Both name and description are required. The name must match the parent directory name.

Optional Frontmatter Fields

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents.
license: Apache-2.0
compatibility: Requires git, docker, jq
allowed-tools: Bash(git:*) Bash(jq:*) Read
metadata:
  author: example-org
  version: "1.0"
---
  

Field Reference

Name Validation Rules

The name field has strict validation rules to ensure consistency across systems:

• Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
• Cannot start or end with a hyphen
• No consecutive hyphens (--)
• Must match the parent directory name exactly

Examples

# Valid names
pdf-processing
data-analysis
code-review
my-skill-v2

# Invalid names
PDF-Processing    # uppercase letters
-pdf              # starts with hyphen
pdf--processing   # consecutive hyphens
pdf_processing    # underscores not allowed
  

Writing Effective Descriptions

The description is critical—it determines when the AI activates your skill. A good description explains both what the skill does AND when to use it.

Good Description

description: Extracts text and tables from PDF files, fills PDF forms, 
  and merges multiple PDFs. Use when working with PDF documents or when 
  the user mentions PDFs, forms, or document extraction.
  

Poor Description

description: Helps with PDFs.
  

The first description gives the AI clear signals about when to activate: mentions of PDFs, forms, document extraction, merging, or text extraction. The second description is too vague to be useful.

Description Patterns

Effective descriptions often follow this pattern:

[Action verbs describing capabilities]. Use when [trigger conditions].
  

Examples:

• "Creates Jekyll blog posts from source materials. Use when asked to write a blog post or document a project."
• "Deploys applications to Kubernetes clusters. Use when the user mentions deployment, k8s, or cluster operations."
• "Generates API documentation from TypeScript interfaces. Use when documenting APIs or generating OpenAPI specs."

Progressive Disclosure

Agent Skills use progressive disclosure to optimize context efficiency. Not all content loads at once—the system loads only what's needed:

1. Metadata (~100 tokens): name + description loaded at startup for all skills
2. Instructions (<5000 tokens): Full SKILL.md loaded only when skill activates
3. Resources (as needed): Files in references/ or assets/ loaded only when explicitly referenced

This architecture means you should:

• Keep SKILL.md under 500 lines — Move detailed reference material to references/
• Put frequently-needed instructions in SKILL.md — This loads automatically on activation
• Use references for edge cases and deep details — Keeps main instructions focused

File References

When your skill needs to reference supporting files, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for API details.

Use the template at `assets/TEMPLATE.html` as a starting point.

Run the script: `scripts/process.py`
  

Best practices for file references:

• Keep references one level deep—avoid nested reference chains
• Use descriptive filenames that indicate content
• Include a brief description of what each referenced file contains

Complete Example

Here's a complete example of a skill that generates code review comments:

---
name: code-review
description: Generates constructive code review comments following team 
  conventions. Use when reviewing pull requests or when the user asks 
  for code review, feedback on code, or PR comments.
license: MIT
compatibility: Works with any programming language
metadata:
  author: your-team
  version: "1.2"
---
  

# Code Review Skill

Generate helpful, constructive code review comments.

## Review Principles

1. **Be specific**: Point to exact lines and explain the issue
2. **Be constructive**: Suggest improvements, don't just criticize
3. **Be kind**: Assume positive intent from the author
4. **Be selective**: Focus on important issues, not nitpicks

## Comment Format

Use this format for review comments:

```
**[Category]** Brief summary

Detailed explanation of the issue or suggestion.

**Suggested change:**
\`\`\`language
improved code here
\`\`\`
```

## Categories

- **Bug**: Logic error or incorrect behavior
- **Security**: Potential vulnerability
- **Performance**: Inefficient code
- **Style**: Formatting or naming conventions
- **Clarity**: Hard to understand code
- **Suggestion**: Optional improvement

## Workflow

1. Read the entire diff to understand context
2. Identify the most important issues (max 5-7 comments)
3. Write comments using the format above
4. Review your comments for tone before posting
  

Validation

You can validate your skill using the official reference library:

# Install the validation tool
pip install skills-ref

# Validate your skill
skills-ref validate ./my-skill

# Read skill properties (outputs JSON)
skills-ref read-properties ./my-skill

# Generate <available_skills> XML for agent prompts
skills-ref to-prompt ./my-skill
  

Common validation errors:

• Name mismatch: The name field doesn't match the directory name
• Missing description: The required description field is empty
• Invalid characters: Name contains uppercase letters, underscores, or other invalid characters
• File too large: SKILL.md exceeds recommended size limits

Note: The skills-ref library is intended for demonstration and validation purposes. For production workflows, consider integrating validation into your CI pipeline.

Best Practices

Do

• Write descriptions that explain both capability and trigger conditions
• Keep SKILL.md focused and under 500 lines
• Use clear section headers for easy scanning
• Include concrete examples of inputs and outputs
• Test your skill with various prompts to ensure it activates correctly
• Version your skills alongside your code in source control

Don't

• Pack everything into SKILL.md—use references for deep details
• Write vague descriptions like "helps with stuff"
• Create skills that are too narrow (single use) or too broad (always activates)
• Include sensitive information like API keys or credentials
• Create nested chains of references that require multiple file reads
• Install skills from untrusted sources without auditing them first

Security Considerations

Skills provide AI assistants with new capabilities through instructions and code. While this makes them powerful, it also means that malicious skills could introduce vulnerabilities or direct the AI to take unintended actions. Keep these guidelines in mind:

• Install skills only from trusted sources — Verify the author and review the contents before use
• Audit skills before deployment — Read the SKILL.md and any bundled scripts to understand what they do
• Pay attention to dependencies — Check what external tools or packages the skill requires
• Test in isolation first — Try new skills in a non-production environment before relying on them

Conclusion

Agent Skills provide a powerful way to extend your AI coding assistant with domain-specific knowledge. By following the SKILL.md format specification, you can create reusable instruction modules that activate when relevant and stay efficient when dormant.

The key principles to remember:

• Structure matters: Use the standardized directory layout with SKILL.md as the required entry point
• Descriptions are critical: Write descriptions that clearly signal when the skill should activate
• Progressive disclosure: Keep main instructions focused, use references for details
• Validate early: Test your skills with various prompts to ensure they work as expected

Start with a simple skill for a workflow you repeat often, and expand from there. Once you experience the productivity gains of having your AI assistant understand your project's conventions, you'll find more opportunities to create skills that capture your team's institutional knowledge.

For the full specification and additional examples, visit the Agent Skills documentation.