a-i--skills

Skill Specification

This document defines the format and requirements for AI agent skills.

File Structure

Every skill must have this minimal structure:

skill-name/
└── SKILL.md          # Required: main skill file

Optional directories:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: supporting documentation
└── assets/           # Optional: templates, images, fonts

SKILL.md Format

The SKILL.md file consists of two parts: YAML frontmatter and Markdown content.

YAML Frontmatter

The file must begin with YAML frontmatter delimited by ---:

---
name: skill-name
description: What the skill does and when to use it.
license: MIT
---

Required Fields

Field	Type	Description
name	string	Skill identifier. Must match the directory name exactly.
description	string	Task-focused description of what the skill does.

Optional Fields

Field	Type	Description
license	string	License type (e.g., MIT, Apache-2.0, Complete terms in LICENSE.txt)
complexity	string	Skill complexity level: beginner, intermediate, or advanced
time_to_learn	string	Estimated time to learn: 5min, 30min, 1hour, or multi-hour
prerequisites	list	Skills that should be learned first (list of skill names)
tags	list	Searchable keywords for discovery
metadata	object	Additional metadata (e.g., source, adapted-by, category)
inputs	list	What the skill expects as input (e.g., [source-code, openapi-spec])
outputs	list	What the skill produces (e.g., [test-report, mcp-server-code])
side_effects	list	Environment changes the skill may cause (e.g., [creates-files, runs-commands])
triggers	list	Activation conditions (see Activation Conditions)
complements	list	Skills that pair well with this one (list of skill names)
includes	list	Bundle: skills to install together (list of skill names; must exist)
tier	string	Quality tier: core (curated, reviewed) or community

Field Constraints

name

• Must exactly match the parent directory name
• Lowercase letters, numbers, and hyphens only
• Pattern: ^[a-z0-9-]+$
• Examples: tdd-workflow, mcp-builder, cv-resume-builder

description

• Should describe what the skill does and when to use it
• Task-focused, not agent-focused (describe the task, not Claude)
• Use third-person phrasing: “Guide for creating…” not “Use this to create…”
• Include trigger phrases that help agents recognize when to apply the skill
• Length: 20-600 characters (enforced by validation)

license

• Required for skills contributed to this repository
• Use MIT for open-source skills
• Use Complete terms in LICENSE.txt if providing a separate license file

complexity (optional)

• One of: beginner, intermediate, advanced
• beginner: Foundational skills with no prior knowledge required
• intermediate: Requires some domain experience
• advanced: Requires significant expertise or multiple prerequisite skills

time_to_learn (optional)

• One of: 5min, 30min, 1hour, multi-hour
• Estimated time for a developer to become productive with the skill
• 5min: Quick reference, simple patterns
• 30min: Standard skill with moderate depth
• 1hour: Comprehensive skill with multiple concepts
• multi-hour: Deep skill requiring significant study

prerequisites (optional)

• List of skill names that should be learned first
• Use exact skill names (e.g., testing-patterns, api-design-patterns)
• Example: ```yaml prerequisites:
  • testing-patterns
  • backend-implementation-patterns ```

tags (optional)

• List of searchable keywords
• Use lowercase, no spaces (use hyphens)
• Include synonyms and related terms
• Example: ```yaml tags:
  • api
  • rest
  • graphql
  • openapi ```

inputs (optional)

• List of input types the skill expects
• Use lowercase, hyphen-separated values
• Describes what the skill needs to operate on
• Example: ```yaml inputs:
  • source-code
  • openapi-spec ```

outputs (optional)

• List of output types the skill produces
• Use lowercase, hyphen-separated values
• Describes what artifacts the skill creates
• Example: ```yaml outputs:
  • test-report
  • mcp-server-code ```

side_effects (optional)

• List of environment changes the skill may cause
• Values must be from the known set: creates-files, modifies-git, runs-commands, network-access, installs-packages, reads-filesystem
• Example: ```yaml side_effects:
  • creates-files
  • runs-commands ```

triggers (optional)

• List of activation conditions that tell agents when to suggest this skill
• See Activation Conditions for the full syntax specification
• Example: ```yaml triggers:
  • user-asks-about-mcp
  • file-type:*.py
  • project-has-package-json ```

complements (optional)

• List of skill names that pair well with this skill
• Each value should reference an existing skill name (warning if missing)
• Example: ```yaml complements:
  • tdd-workflow
  • verification-loop ```

includes (optional)

• List of skill names to install together (bundle/pack pattern)
• Each value must reference an existing skill name (error if missing)
• Only meaningful for “pack” skills that aggregate others
• Example: ```yaml includes:
  • api-design-patterns
  • testing-patterns
  • deployment-cicd ```

tier (optional)

• One of: core, community
• core: Curated, reviewed skills maintained by the repository team
• community: Community-contributed skills with standard validation
• See Core vs Community for promotion criteria

Markdown Content

After the frontmatter, include Markdown instructions:

---
name: example-skill
description: Example skill demonstrating the format.
license: MIT
---

# Skill Title

Brief overview of what this skill provides.

## When to Use

Describe scenarios where this skill applies.

## Process

Step-by-step workflow or instructions.

## Examples

Concrete examples showing the skill in action.

Optional Directories

scripts/

Executable code (Python, Bash, etc.) for deterministic tasks.

• Include when the same code is repeatedly needed
• Scripts may be executed without loading into context
• Use for tasks requiring deterministic reliability

Example: scripts/rotate_pdf.py

references/

Documentation loaded into context as needed.

• Database schemas, API documentation
• Company policies, domain knowledge
• Detailed guides too long for SKILL.md

Keep SKILL.md lean; move detailed information to references.

assets/

Files used in skill output (not loaded into context).

• Templates (PowerPoint, Word, etc.)
• Images, icons, fonts
• Boilerplate code directories

Example: assets/template.pptx

Validation

Run the validation script to check your skill:

python3 scripts/validate_skills.py --collection example --unique

The validator checks:

• YAML frontmatter is present and valid
• Required fields (name, description) exist
• name matches the directory name
• name uses valid characters (lowercase alphanumeric + hyphens)

Examples

Minimal Skill

---
name: simple-helper
description: A simple helper skill for basic tasks.
license: MIT
---

# Simple Helper

Instructions for the skill go here.

Complete Skill

---
name: complex-workflow
description: Guide for complex multi-step workflows requiring external tools and detailed documentation. Use when implementing enterprise-grade solutions.
license: MIT
---

# Complex Workflow Guide

## Overview

This skill provides a comprehensive framework for...

## Process

### Phase 1: Planning

1. Understand requirements
2. Review documentation in `references/`

### Phase 2: Implementation

1. Use scripts in `scripts/` for automation
2. Apply templates from `assets/`

## References

See `references/detailed-guide.md` for in-depth documentation.

Best Practices

1. Be specific in descriptions - Include trigger phrases and use cases
2. Keep SKILL.md focused - Move detailed docs to references/
3. Use progressive disclosure - Essential info in SKILL.md, details in references
4. Avoid duplication - Information should live in one place only
5. Test with validation - Run validate_skills.py before committing

This site is open source. Improve this page.