The SKILL.md Spec — Detail · AI Agent Skills

Why a Spec?

The Problem with Ad-Hoc Instructions

Before skills, teams relied on copy-paste system prompts, scattered README notes, and tribal knowledge. No reuse, no versioning, no composability.

System prompts vanish per session
No standard format across tools
Cannot compose procedures
No review or audit trail

Frontmatter Fields

YAML Metadata — The Tier 1 Surface

Field	Required	Purpose
name	Yes	Kebab-case identifier
description	Yes	What this skill does (<200 chars)
version	No	Semantic version
author	No	Skill creator
tags	No	Discovery keywords
triggers	No	Activation patterns

---
name: deploy-to-vercel
description: >
  Deploy a Next.js app to
  Vercel with env var setup
version: 1.2.0
author: sangam
tags: [deploy, vercel, nextjs]
triggers:
  - "deploy to vercel"
  - "push to production"
---

Directory Structure

Skill Folder Layout

.claude/skills/
  deploy-to-vercel/
    SKILL.md      # definition
    scripts/     # automation
    references/  # docs
    assets/      # templates

Only SKILL.md is required. All subdirectories are optional Tier 3 resources.

The Body

Markdown Instructions — The Tier 2 Payload

The body is standard markdown that follows the YAML frontmatter. It contains the actual procedure the agent executes.

Structure conventions:

Use headings for major sections
Number steps for sequential procedures
Use code blocks for commands and templates
Reference other skills with relative paths
Include guard clauses (check X before doing Y)
Keep under 5,000 tokens total

## Pre-flight Checks
1. Verify vercel.json exists
2. Check all env vars are set
3. Run npm run build locally

## Deploy
1. Run vercel --prod
2. Verify deployment URL
3. Run smoke tests

## Rollback
If deploy fails:
1. Run vercel rollback
2. Check vercel logs

Real Example

Complete SKILL.md — Content Engine

---
name: content-engine
description: Generate blog + social posts from a topic with infographics
---

## Workflow
1. Read EditorialDNA.md for voice and tone
2. Research topic using GitHub search + vendor docs
3. Generate blog post (min 2,500 words, MDX format)
4. Create infographic using /sangam-infographic skill
5. Draft LinkedIn post following LinkedInDNA.md
6. Push blog to content/blog/, infographic to public/infographics/

## References
# Agent loads these from references/ when needed (Tier 3)
- references/seo-checklist.md
- references/editorial-dna.md

Skill File Anatomy

Visual Breakdown of SKILL.md

Scripts & Assets

Tier 3 Resources

scripts/ — Shell or Python automation helpers. The skill body references them; agent loads when execution reaches that step.

references/ — Documentation the skill might need. Checklists, API specs, style guides.

assets/ — Templates, config files, images. Copied or used during procedure execution.

All optional. Never pre-loaded. Loaded only when the skill explicitly requests them.

Composition

Skills Referencing Skills

A skill can invoke other skills by name. This enables modular procedures where complex workflows delegate to focused sub-skills.

## Deploy Flow
Run /lint-check skill
Run /test-suite skill
Execute deployment steps
Run /smoke-test skill

Dependency chains are resolved at runtime. No circular references.

Spec Comparison

SKILL.md vs Alternative Approaches

Approach	Portability	Composable	Version Control	Context Cost	Reusable
SKILL.md	Any platform	Yes	Git-native	~100 tokens	Yes
System prompts	Per-session	No	Manual	Full size	No
.cursorrules	Cursor only	No	Git	Medium	Limited
Custom GPTs	OpenAI only	No	None	Medium	Sharable
CLAUDE.md	Claude only	Partial	Git	Medium	Per-project

Best Practices

Writing Good Skills

One procedure per skill file
Keep body under 5K tokens
Use descriptive kebab-case names
Write descriptions that match user intent
Include guard clauses and rollback steps
Test before sharing to a registry
Version when interface changes