/skill-authoring

name: skill-authoring
description: >-
  Guide for creating and auditing DAAF skills (SKILL.md). Covers frontmatter, metadata vocabulary, progressive disclosure, decision trees, reference files. Use when creating, reviewing, or debugging skill loading. For agent files, use agent-authoring.
metadata:
  audience: any-agent
  domain: skill-development

Skill Authoring

Guide for creating and auditing DAAF agent skills. Covers SKILL.md format, frontmatter requirements and validation rules, controlled vocabulary for metadata, progressive disclosure patterns, decision trees, reference files, and bundled resource organization. Use when creating a new skill, reviewing or auditing skill structure and frontmatter, or debugging skill loading and triggering issues. For creating agent definition files (.claude/agents/*.md), use agent-authoring instead.

Quick reference for creating well-structured Skills. Use decision trees below to find guidance, then load detailed references as needed.

What is a Skill?

A Skill is a reusable instruction set that extends agent capabilities:

• **SKILL.md file**: Required entry point with YAML frontmatter + Markdown body
• **Progressive disclosure**: Metadata loaded at startup, body on trigger, resources on-demand
• **Bundled resources**: Optional `scripts/`, `references/`, `assets/` directories
• **On-demand loading**: Agent calls `skill({ name: "skill-name" })` to load

How to Use This Skill

Reference File Structure

| File | Purpose | When to Read | |------|---------|--------------| | `quickstart.md` | Minimal skill, directory setup | Creating first skill | | `frontmatter.md` | YAML spec, validation rules, description writing | Writing frontmatter | | `structure.md` | Body patterns, section templates, content patterns | Organizing content | | `progressive-disclosure.md` | Three-level loading, splitting | Managing token budget | | `references-resources.md` | scripts/, references/, assets/ | Adding bundled resources | | `testing-iteration.md` | Test prompts, iteration workflow, multi-model testing | Validating and improving skills | | `gotchas.md` | Anti-patterns, validation errors, diagnostics | Debugging or reviewing |

Reading Order

1. **Creating a skill?** Start with `quickstart.md` then `frontmatter.md` 2. **Structuring content?** Read `structure.md` then `progressive-disclosure.md` 3. **Adding resources?** See `references-resources.md` 4. **Testing and improving?** See `testing-iteration.md` 5. **Having issues?** Check `gotchas.md` first

Quick Decision Trees

"I need to create a skill"

Creating a new skill?
├─ Where to put it → ./references/quickstart.md
├─ Minimal example → ./references/quickstart.md
├─ Write frontmatter → ./references/frontmatter.md
├─ Name validation → ./references/frontmatter.md
└─ Description best practices → ./references/frontmatter.md

"I need to structure the body"

Structuring SKILL.md body?
├─ Workflow-based (sequential steps) → ./references/structure.md
├─ Task-based (tool collection) → ./references/structure.md
├─ Reference-based (standards/specs) → ./references/structure.md
├─ Capabilities-based (features) → ./references/structure.md
├─ Decision tree format → ./references/structure.md
└─ Table conventions → ./references/structure.md

"I need to manage content size"

Content too large?
├─ Understand three-level loading → ./references/progressive-disclosure.md
├─ When to split into references → ./references/progressive-disclosure.md
├─ Domain-specific organization → ./references/progressive-disclosure.md
├─ Framework/variant splitting → ./references/progressive-disclosure.md
└─ Token budget guidelines → ./references/progressive-disclosure.md

"I need to add resources"

Adding bundled resources?
├─ Executable scripts → ./references/references-resources.md
├─ Documentation files → ./references/references-resources.md
├─ Template assets → ./references/references-resources.md
├─ When to use each type → ./references/references-resources.md
└─ Directory structure → ./references/references-resources.md

"I need to test or improve a skill"

Testing or iterating?
├─ Create test prompts → ./references/testing-iteration.md
├─ Test triggering accuracy → ./references/testing-iteration.md
├─ Iterate based on feedback → ./references/testing-iteration.md
├─ Test across models → ./references/testing-iteration.md
└─ Observe navigation patterns → ./references/testing-iteration.md

"Something isn't working"

Debugging a skill?
├─ Skill not loading → ./references/gotchas.md
├─ Skill undertriggering → ./references/gotchas.md
├─ Skill overtriggering → ./references/gotchas.md
├─ Validation errors → ./references/gotchas.md
├─ Name format issues → ./references/frontmatter.md
├─ Description too long → ./references/frontmatter.md
└─ Common anti-patterns → ./references/gotchas.md

Quick Reference

Minimal SKILL.md Template

---
name: my-skill-name
description: What this skill does. When to use it (specific triggers).
metadata:
  audience: target-users
  domain: skill-domain
---

# My Skill Name

Brief intro sentence.

## Section 1

Content here.

Directory Structure

.claude/skills/<name>/
├── SKILL.md              # Required
├── scripts/              # Optional: executable code
├── references/           # Optional: documentation
└── assets/               # Optional: templates, images

Frontmatter Validation Rules

| Field | Required | Constraints | |-------|----------|-------------| | `name` | Yes | Lowercase alphanumeric + hyphens, 1-64 chars, no leading/trailing/consecutive hyphens | | `description` | Yes | 1-1024 chars, no angle brackets (`<` `>`), include what + when | | `metadata` | No | Key-value pairs (strings) |

Name Validation Regex

^[a-z0-9]+(-[a-z0-9]+)*$

Content Limits

| Component | Limit | Notes | |-----------|-------|-------| | Name | 64 chars | Lowercase hyphen-case | | Description (frontma