Skill Authoring

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

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

Name Validation Regex

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

Content Limits

Core Principles

Essential Do's

• Before creating a new skill, read 1-2 existing skills of the same type as structural exemplars (e.g., for data source skills, read an existing data source SKILL.md; for tool skills, read polars or plotnine)
• Include "what it does" AND "when to use it" in description
• Keep frontmatter description ≤250 chars — this is the ONLY text agents see when deciding whether to load a skill; it gets truncated at 250 chars in the system prompt
• Preserve the full description as a plain paragraph immediately after the # Title heading in the body — this provides complete context once the skill is loaded
• Prioritize in the 250-char budget: (1) what it is, (2) key triggers/use cases, (3) disambiguation from similar skills (e.g., "For FE use pyfixest; for GLM use statsmodels")
• Write descriptions in third person ("Processes files" not "I help you process files")
• Make descriptions slightly "pushy" to combat undertriggering
• Front-load important words in description (may be truncated in UI)
• Explain why behind instructions, not just what
• Use decision trees for navigation
• Keep SKILL.md under 500 lines
• Split large content into references/ files
• Use tables for quick lookup
• Use consistent terminology throughout (pick one term, stick with it)
• Test skills with realistic prompts before finalizing
• Test scripts before including
• Include metadata references (codebook URLs) for data source skills — see datasets-reference.md codebook column

Essential Don'ts

• Don't include README.md, CHANGELOG.md, or auxiliary docs
• Don't put "When to Use" sections in body (loaded too late)
• Don't duplicate content between SKILL.md and references
• Don't nest references more than one level deep
• Don't use angle brackets in description
• Don't start/end name with hyphens
• Don't use heavy-handed ALWAYS/NEVER/MUST in all caps — explain reasoning instead
• Don't offer too many options — provide a default with an escape hatch
• Don't include time-sensitive information (use "Old patterns" <details> sections if needed)
• Don't use Windows-style backslash paths (always forward slashes)

Skill Registration

Skills are automatically discovered via their YAML frontmatter — the orchestrator sees all skills listed in the system message at conversation start. No manual registration is needed for triggering. Once the skill's SKILL.md is placed in .claude/skills/{skill-name}/, it becomes available immediately.

Framework integration beyond discovery: If the skill should be preloaded by specific agents (via skills: frontmatter), referenced in pipeline stage mappings, or wired into workflow documentation, additional registration is required. See agent_reference/FRAMEWORK_INTEGRATION_CHECKLIST.md § 1 (items S8-S10) for the complete list of conditional integration points.

Data Source Skills: Metadata References

When authoring a data source skill, include a codebook reference section if codebooks exist for the source. Follow the existing pattern (modeled after PSEO):

### [Source] Codebooks

| Dataset | Codebook Path |
|---------|---------------|
| ... | `path/to/codebook_name` |

> Codebooks are `.xls` files on both mirrors. See `datasets-reference.md` for full catalog
> and `fetch-patterns.md` for `get_codebook_url()`. For human reference — not parsed programmatically.

The codebook path comes from the codebook column in datasets-reference.md. Metadata files are for human reference only — they are not parsed programmatically by the pipeline.

Topic Index