Skill Writer Guide

Overview

This skill provides comprehensive guidance for creating Agent Skills that follow the official Agent Skills specification. Agent Skills are a simple, open format for giving agents new capabilities and expertise through folders of instructions, scripts, and resources.

What are Agent Skills?

Agent Skills are:

Portable: Work across different AI platforms (Claude, GPT, Copilot, etc.)
Filesystem-based: Simple directory structure with markdown files
Modular: Each skill is self-contained and reusable
Open format: No vendor lock-in, community-driven standard

Creating a New Agent Skill

1. Directory Structure

Every Agent Skill lives in its own directory:

skill-name/
├── SKILL.md           # Required: Main skill file with metadata and instructions
├── scripts/           # Optional: Helper scripts or tools
├── references/        # Optional: Supporting documentation
└── assets/            # Optional: Images, files, or other resources

2. SKILL.md Format

The SKILL.md file is the heart of every skill. It has two parts:

Part 1: YAML Frontmatter (Required)

At the top of SKILL.md, include YAML frontmatter with metadata:

---
name: skill-name                    # Required: lowercase, max 64 chars, matches folder name
description: Brief description      # Required: max 1024 chars, explain what and when
license: MIT                        # Optional: license identifier or file path
compatibility: Linux, Python 3.10+  # Optional: system requirements
metadata:                           # Optional: custom key-value pairs
  author: your-name
  version: "1.0"
  category: development
allowed-tools: tool1 tool2         # Optional/Experimental: approved tools
---

Required Fields:

name: Skill identifier (lowercase, hyphens allowed, no consecutive hyphens)
description: Clear explanation of:
- What the skill does
- When to use it
- Key capabilities

Optional Fields:

license: License type (e.g., MIT, Apache-2.0) or path to LICENSE file
compatibility: System requirements, dependencies
metadata: Any additional info (author, version, tags, etc.)
allowed-tools: List of tools the skill can use (experimental feature)

Part 2: Markdown Body (Instructions)

After the frontmatter, write clear instructions in markdown format:

# Skill Name Guide

## Overview
Brief introduction to the skill's purpose and capabilities.

## Quick Start
Simple example to get started quickly.

## Main Instructions
Step-by-step guidance organized by task or feature.

## Common Tasks
Frequent use cases with examples.

## Examples
Real-world examples with input/output.

## Troubleshooting
Common issues and solutions.

## Reference
Additional details, edge cases, advanced usage.

3. Writing Effective Instructions

Best Practices:

Be Clear and Specific
- Use simple, direct language
- Provide step-by-step instructions
- Include code examples where relevant
Structure for Scannability
- Use headers to organize content
- Break long sections into subsections
- Use lists, tables, and code blocks
Include Examples
- Show both input and output
- Cover common use cases
- Demonstrate edge cases
Keep it Focused
- One skill = one capability domain
- Aim for under 5000 tokens
- Link to references for details
Make it Actionable
- Provide complete, working examples
- Include error handling patterns
- Show command-line usage when relevant

4. Optional Subdirectories

scripts/

Place executable scripts, tools, or programs
Include installation instructions in SKILL.md
Document each script's purpose and usage

references/

Additional documentation
API references
Detailed guides
Link from SKILL.md with relative paths

assets/

Images, diagrams, or visual aids
Sample files or templates
Reference with relative paths from skill root

Complete Example

Here's a minimal but complete skill:

hello-world/
└── SKILL.md

hello-world/SKILL.md:

---
name: hello-world
description: Simple example skill that demonstrates the basic structure of an Agent Skill. Use this as a template when creating new skills.
license: MIT
metadata:
  author: example
  version: "1.0"
---

# Hello World Skill

## Overview

This is a minimal example skill that demonstrates the Agent Skills format.

## Instructions

To use this skill:

1. Create a file called `hello.txt`
2. Write "Hello, World!" to the file
3. Display the contents

## Example

```bash
echo "Hello, World!" > hello.txt
cat hello.txt

Expected output:

Hello, World!

Next Steps

Use this template to create more complex skills with additional features.


## Skill Creation Checklist

When creating a new skill, verify:

- [ ] Skill name is lowercase with hyphens only
- [ ] Folder name matches the `name` field in frontmatter
- [ ] YAML frontmatter is valid and complete
- [ ] `name` field is present (required)
- [ ] `description` field is present and clear (required)
- [ ] Description explains WHAT the skill does
- [ ] Description explains WHEN to use it
- [ ] Description is under 1024 characters
- [ ] Instructions are clear and actionable
- [ ] Examples are provided for main use cases
- [ ] Code examples are complete and tested
- [ ] Relative paths are used for internal references
- [ ] Total content is reasonable size (aim for <5000 tokens)
- [ ] All optional files (scripts, references, assets) are documented

## Common Patterns

### Task-Oriented Skills
Focus on accomplishing specific tasks:
- File processing (PDF, Excel, images)
- System administration
- Testing and validation
- Code generation

### Domain Expertise Skills
Provide specialized knowledge:
- Programming languages
- Frameworks and libraries
- APIs and protocols
- Best practices and patterns

### Workflow Skills
Guide multi-step processes:
- Project setup
- Deployment procedures
- Review checklists
- Documentation workflows

## Tips for Success

1. **Start Simple**: Begin with core functionality, add advanced features later
2. **Test Instructions**: Verify examples work as documented
3. **Think Like a User**: What would someone need to know to use this skill?
4. **Iterate**: Skills can evolve—start with v1.0 and improve over time
5. **Be Consistent**: Follow conventions from existing skills in your domain
6. **Document Assumptions**: State prerequisites and dependencies clearly
7. **Handle Errors**: Include troubleshooting for common issues

## Naming Conventions

- Use lowercase letters
- Separate words with hyphens (kebab-case)
- Be descriptive but concise
- Avoid abbreviations unless widely known
- Match folder name to skill name

**Good names:**
- `pdf-processing`
- `web-testing`
- `api-documentation`
- `code-review`

**Avoid:**
- `PDFProcessing` (uppercase)
- `pdf_processing` (underscores)
- `pdfproc` (unclear abbreviation)
- `skill-1` (not descriptive)

## Validation

Before finalizing a skill:

1. **Check YAML Syntax**
   - Use a YAML validator
   - Ensure proper indentation
   - Verify no syntax errors

2. **Test Instructions**
   - Follow your own instructions step-by-step
   - Verify all examples work
   - Check all file paths

3. **Review Content**
   - Proofread for clarity
   - Remove unnecessary complexity
   - Ensure completeness

4. **Check Structure**
   - SKILL.md is at skill root
   - All referenced files exist
   - Paths are relative from skill root

## Resources

- **Specification**: https://agentskills.io/specification
- **Documentation**: https://agentskills.io
- **Examples**: https://github.com/anthropics/skills
- **Community**: https://github.com/agentskills/agentskills
- **Template**: See [references/template.md](references/template.md) for a ready-to-use skill template

## Advanced Features

### Multi-file Skills

For complex skills, organize content across multiple files:

advanced-skill/ ├── SKILL.md # Main instructions and quick start ├── references/ │ ├── api.md # Detailed API documentation │ ├── examples.md # Extended examples │ └── troubleshoot.md ├── scripts/ │ ├── setup.sh # Installation script │ └── helper.py # Utility functions └── assets/ └── diagram.png # Visual aids


Reference from SKILL.md:
```markdown
For detailed API documentation, see [references/api.md](references/api.md).

Using Scripts

When including scripts:

Document clearly in SKILL.md
Make executable (chmod +x script.sh)
Include shebang (#!/bin/bash or #!/usr/bin/env python3)
Add comments explaining key steps
Handle errors gracefully

Example script reference:

## Installation

Run the setup script:

```bash
chmod +x scripts/setup.sh
./scripts/setup.sh

The script will:

Check system requirements
Install dependencies
Configure the environment


### Tool Restrictions

Use the `allowed-tools` field (experimental) to specify approved tools:

```yaml
---
name: secure-skill
description: Skill with restricted tool access
allowed-tools: pdftotext qpdf
---

This helps ensure skills only use vetted, secure tools.

Conclusion

Agent Skills provide a simple, powerful way to give AI agents specialized capabilities. By following this guide and the official specification, you can create high-quality skills that work across platforms and help agents perform better at specific tasks.

Start simple, iterate based on feedback, and share your skills with the community!

skill-writer