Creating a Skill

Initialize a New Skill

Use the CLI to create a new skill project:

This creates a new directory with a SKILL.md template following the agentskills.io spec.

Use a Template

Start with a template for common skill types. Templates use gerund naming (verb-ing form) as recommended by the spec:

Available templates: reviewing-code, processing-pdfs, writing-tests, analyzing-security, documenting-code, debugging-issues, converting-data, calling-apis, explaining-code

Project Structure

A skill is a directory following the agentskills.io structure:

my-skill/
├── SKILL.md           # Required: Instructions (per spec)
├── skill.json         # Optional: Asterism extensions
├── scripts/           # Optional: Executable code
│   └── process.py
├── references/        # Optional: Additional docs
│   └── patterns.md
└── assets/            # Optional: Static resources
    └── template.txt

The only required file is SKILL.md. Per the spec, only name and description are required in frontmatter.

Write Your SKILL.md

Per the agentskills.io spec, only name and description are required:

---
name: reviewing-code
description: Reviews code for quality and security issues. Use when examining PRs or auditing codebases.
---

# Reviewing Code

Reviews code for quality, security, and best practices.

## When to Use

- Reviewing pull requests or merge requests
- Auditing code for security vulnerabilities
- Checking code quality before deployment

## Instructions

1. Read the code carefully, understanding its purpose
2. Check for security vulnerabilities (injection, XSS, auth issues)
3. Evaluate code quality (naming, structure, complexity)
4. Provide constructive feedback with specific suggestions

## Examples

### Example: Review a function
User: "Review this authentication function"
Response: Analyze for security issues, suggest improvements, note what's done well.

## Guidelines

- Start with positive observations before critiques
- Be specific - reference line numbers or function names
- Suggest fixes, not just problems

Naming Convention

Per Anthropic's best practices, use gerund form (verb + -ing) for skill names:

Gerund names describe what the skill does, making them more discoverable.

Description Format

Descriptions should include WHAT the skill does and WHEN to use it:

Use third-person voice (“Reviews...”) not first-person (“I review...”).

Asterism Extensions (Optional)

For additional features, create a skill.json file with Asterism extensions:

{
  "$schema": "https://joinasterism.com/schema/skill.json",
  "name": "reviewing-code",
  "version": "1.0.0",
  "description": "Reviews code for quality and security issues...",
  "author": "your-username",
  "license": "MIT",
  "keywords": ["code-review", "security", "quality"],
  "categories": ["code-quality"],
  "repository": "https://github.com/you/reviewing-code"
}

See the Best Practices guide for more on contracts, capabilities, and testing.

Test Locally

Validate your skill before publishing:

The CLI will warn if your skill exceeds 500 lines or has description quality issues.

Test with Multiple Models

Per Anthropic's guidance, test your skill with different Claude models:

• Claude Haiku: Fast and affordable. If your skill works here, it's well-structured.
• Claude Sonnet: Balanced performance. Most common for production.
• Claude Opus: Most capable. Handles complex reasoning.

A skill that only works on Opus might have instructions that are too vague.