Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/skill-authoring

skill-authoring

Verified

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.

references/frontmatter.md

View on GitHub
# Frontmatter Specification

The YAML frontmatter is the metadata block at the start of every SKILL.md file. It controls skill discovery and triggering.

## Frontmatter Structure

```yaml
---
name: skill-name
description: What this skill does and when to use it.
metadata:
  key1: value1
  key2: value2
---
```

The frontmatter must:
- Start on line 1 with `---`
- Contain valid YAML
- End with `---`
- Produce a dictionary when parsed

## Required Fields

### `name`

The skill identifier. Must match the containing directory name.

**Constraints:**

| Rule | Example Valid | Example Invalid |
|------|---------------|-----------------|
| Lowercase only | `my-skill` | `My-Skill` |
| Alphanumeric + hyphens | `pdf-v2` | `pdf_v2` |
| No leading hyphen | `skill-name` | `-skill-name` |
| No trailing hyphen | `skill-name` | `skill-name-` |
| No consecutive hyphens | `my-skill` | `my--skill` |
| 1-64 characters | `a` to 64 chars | empty or 65+ chars |

**Validation Regex:**

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

**Normalization:**

If you provide a non-conforming name, it gets normalized:

| Input | Normalized |
|-------|------------|
| `My Skill` | `my-skill` |
| `PDF_Processor` | `pdf-processor` |
| `--test--` | `test` |
| `foo  bar` | `foo-bar` |

### `description`

The primary triggering mechanism. This is what agents see when deciding whether to load a skill.

**Constraints:**

| Rule | Limit |
|------|-------|
| Length | **≤1,024 characters** (validation limit — Agent Skills spec; description must be non-empty) |
| Display cap | Combined `description` + `when_to_use` is truncated at **1,536 characters** per skill in the skill listing (the `skillListingMaxDescChars` default); the truncation breakdown is reported by `/doctor`, not a startup notification |
| No angle brackets | Cannot contain `<` or `>` |
| Non-empty | Must have content after trimming whitespace |

> **Why description length matters.** The description is the ONLY text agents see when deciding whether to load a skill, so it should be complete and information-rich — a compressed teaser that undertriggers is worse than a longer description that triggers correctly. Three constraints govern length:
>
> 1. **Validation limit (1,024 chars):** The `description` field alone must stay within 1,024 characters or skill validation fails.
> 2. **Display cap (1,536 chars combined):** The skill listing truncates the combined `description` + `when_to_use` text at 1,536 characters per skill (the `skillListingMaxDescChars` default; raised from 250 in Claude Code v2.1.105). The truncation breakdown is reported by `/doctor` (since 2.1.144), not a startup notification.
> 3. **Aggregate listing budget (~1% of context):** The skill listing as a whole shares a budget of roughly 1% of the model's context window across ALL skills. DAAF has 40+ skills competing for this shared resource — when the listing overflows, descriptions for the least-invoked skills are dropped first (diagnosable with `/doctor`). This is why economy still matters even though the per-skill caps are generous: a bloated description doesn't just cost its own skill, it can crowd out others. Because the budget scales with the context window, the same skill inventory is more likely to overflow on smaller-window models — economy matters even more there.
>
> These numbers were verified against the Claude Code settings reference on 2026-09-05 (CC 2.1.261) and are configurable: `skillListingMaxDescChars` (positive integer, default 1,536) sets the per-skill listing cap, and `skillListingBudgetFraction` (a fraction >0 and ≤1, default 0.01 = 1% of the context window; DAAF sets 0.1 as a guardrail — well above any listing size DAAF ships, so truncation only fires if the listing ever grows past 10% of the window) sets the aggregate listing budget. If observed behavior differs, verify against current Claude Code docs before assuming this reference is correct.

**Must Include:**

1. **What the skill does** - Functionality overview (identity + scope)
2. **When to use it** - Key triggering conditions
3. **Disambiguation** - What NOT to use this for, especially when similar skills exist (e.g., "For FE use pyfixest; for GLM use statsmodels")
4. **Third-person voice** - Write as "Processes files" not "I help you process files"

**Content priorities** (what earns its characters, in order — longer is allowed, but every sentence should improve triggering accuracy or prevent misuse):
1. Core identity (what it is) — always include
2. Key disambiguation (prevents wrong-skill loading) — always include
3. Most common triggers — the top 2-3, plus critical caveats that change how the skill is used
4. Scope limitations — include when they prevent wrong-skill loading
5. Exhaustive coverage/feature lists — move to body description; these consume shared listing budget without improving triggering

As a calibration anchor: most well-calibrated DAAF descriptions land in the 300-700 character range (the polars example later in this file is ~418 chars). Treat that band as a starting point, not a rule — go longer when triggering accuracy genuinely demands it.

**Good Examples:**

```yaml
# Good: Clear what + when
description: Generate SQL queries for analytics. Use when asked to query databases, create reports, or analyze data with SQL.

# Good: Specific triggers
description: Fix failing GitHub Actions CI. Use when PR checks fail, CI is red, or asked to debug GitHub Actions workflows.

# Good: File-type trigger
description: Process and manipulate PDF files. Use when working with .pdf files, rotating pages, merging documents, or extracting text from PDFs.
```

**Bad Examples:**

```yaml
# Bad: No "when to use"
description: A helpful skill for various tasks.

# Bad: Too vague
description: Does things with files.

# Bad: Contains angle brackets
description: Use <this> when needed.

# Bad: "When to use" in wrong place (will be in body, loaded too late)
description: Helps with testing.
# Then in body: "## When to Use This Skill" <-- WRONG
```

### Combating Undertriggering

Claude tends to undertrigger skills — not using them when they'd be useful. Make descriptions slightly "pushy" by including contexts where the skill should activate even if the user doesn't explicitly name it.

```yaml
# Standard (may undertrigger)
description: Build dashboards to display data.

# Pushy (better triggering)
description: Build dashboards to display data. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of data, even if they don't explicitly ask for a "dashboard."
```

### Combating Overtriggering

If a skill loads for unrelated queries, add negative triggers to narrow scope:

```yaml
description: Advanced statistical analysis for CSV datasets. Use for regression modeling, clustering, and hypothesis testing. Do NOT use for simple data exploration or basic charting (use data-viz skill instead).
```

### Full Description in Body

DAAF convention: write an **expanded body description** as a plain paragraph immediately after the `# Title` heading in the SKILL.md body. It elaborates beyond the frontmatter rather than duplicating it, guaranteeing agents have complete context once the skill is loaded — robust to any listing truncation, aggregate-budget drops, or configuration differences, and a natural home for detail that doesn't earn its place in the shared listing budget.

**Pattern:**

```markdown
---
name: my-skill
description: >-
  Complete, information-rich description. What it does, key triggers and use
  cases, disambiguation from similar skills.
metadata:
  audience: research-coders
  domain: python-library
---

# My Skill

Expanded description elaborating on the frontmatter. Covers all
capabilities, specific triggers, scope limitations, disambiguation guidance,
and any other context that helps agents use this skill correctly. This text
is only visible after the skill is loaded — it does NOT influence triggering
decisions, but it provides essential orientation once an agent is working
with the skill.

[Rest of SKILL.md body...]
```

**Rules:**
- The body description is a plain paragraph (no heading, no blockquote) directly after `# Title`
- It should expand and elaborate beyond the frontmatter — detailed scope, additional triggers, fine-grained disambiguation, anything moved out of the listing for budget economy
- It should NOT duplicate the frontmatter description verbatim — expand and elaborate instead
- Existing DAAF skills follow this pattern as of 2026-03-29

### Naming Conventions

Consider using **gerund form** (verb + -ing) for skill names, as this clearly describes the activity the skill provides:

- `processing-pdfs` — clearly an activity
- `analyzing-spreadsheets` — clearly an activity
- `managing-databases` — clearly an activity

Acceptable alternatives include noun phrases (`pdf-processing`) or action-oriented names (`process-pdfs`). Avoid vague names like `helper`, `utils`, or `tools`.

## Optional Fields

### `when_to_use`

An optional field for triggering guidance, separate from the `description`. In the skill listing, its text is appended to the `description` — the combined text is what counts toward the 1,536-char display cap.

```yaml
when_to_use: Use when working with .pdf files, rotating pages, or extracting text.
```

DAAF does not require this field: existing DAAF skills fold triggering guidance directly into the `description` ("what it does" + "when to use it" in one field), which displays identically. Treat `when_to_use` as an escape hatch when a description is approaching its 1,024-char validation limit and triggering guidance needs more room — not as a default convention.

### `metadata`

Additional key-value pairs for categorization. Values must be strings.

```yaml
metadata:
  audience: research-coders
  domain: python-library
  library-version: "1.x"
```

### Controlled Vocabulary

DAAF uses a controlled vocabulary for `audience` and `domain` to enable consistent skill routing. Use the exact values below — do not invent new values without updating this spec.

#### `audience` — Which agent role benefits from this skill?

| Value | Targets | Example Skills |
|-------|---------|----------------|
| `any-agent` | Broadly useful across roles | data sources, data-scientist, skill-authoring |
| `research-orchestrator` | Orchestrator agent only | daaf-orchestrator |
| `research-planner` | Planning/discovery agents | education-data-explorer |
| `research-coders` | Anyone writing or reviewing code | Python libraries, education-data-query |
| `research-writers` | Anyone writing or reviewing narrative | science-communication |

> **Canonical value note:** `research-coders` is the canonical `audience` value for skills targeting code-writing or code-reviewing agents. Some older skill text uses the legacy phrasing "code-producing agents" — normalization to `research-coders` is in progress. Always use `research-coders` in new skills.

#### `domain` — What functional category does this skill belong to?

| Value | Covers | Example Skills |
|-------|--------|----------------|
| `data-source` | Reference guides for specific datasets | education-data-source-ccd, election-data-source-countypres |
| `data-access` | Fetching/discovering data | education-data-query, education-data-explorer |
| `data-documentation` | Provenance, caveats, interpretation | education-data-context |
| `python-library` | Python library syntax/API reference | polars, plotly, statsmodels |
| `r-library` | R library syntax/API reference | tidyverse, fixest, gt |
| `cross-language` | Cross-language translation/annotation guidance | python-r-translation, stata-r-translation |
| `research-methodology` | Analytical approach, rigor, mindset | data-scientist |
| `research-orchestration` | Workflow/pipeline management | daaf-orchestrator |
| `research-communication` | Translating findings for audiences | science-communication |
| `skill-development` | Meta-skills for building skills/agents | skill-authoring, agent-authoring |

#### Other Standard Metadata Keys

| Key | Purpose | Example Values | When to Include |
|-----|---------|----------------|-----------------|
| `library-version` | Library version tracked by the skill | `"1.x"`, `"0.40.0"` | Python and R library skills only |
| `skill-authored` | ISO-8601 creation date | `"2026-02-09"` | Data source skills (required) |
| `skill-last-updated` | ISO-8601 last-verified date | `"2026-02-09"` | Data source skills (required); Python and R library skills (recommended) |

> **Provenance in metadata:** Data source skills MUST include `skill-authored` and `skill-last-updated` as metadata keys. These track when the skill was created and when it was last verified against actual data. On updates, change only `skill-last-updated`; `skill-authored` remains fixed. If `skill-last-updated` is more than a few months old, treat skill claims with caution — re-run data onboarding to re-verify.

> **Library skill staleness:** Library skills (Python and R) SHOULD include `skill-last-updated` to signal when the `library-version` claim was last verified. Library APIs evolve — if the tracked version is outdated, the skill's syntax examples and API patterns may have drifted.

> **Metadata routing semantics:** The `audience` and `domain` fields are used for skill inventory management, human auditing, and maintenance — not for programmatic agent routing. Agent skill selection is driven by description text matching and explicit skill name references in orchestrator dispatch tables and agent frontmatter. These fields help maintainers answer questions like "show me all skills relevant to code-writing agents" or "list all data source skills" without affecting runtime behavior.

## Field Reference Table

| Field | Required | Type | Max Length | Notes |
|-------|----------|------|------------|-------|
| `name` | Yes | String | 64 chars | Lowercase hyphen-case |
| `description` | Yes | String | 1,024 chars (validation limit) | No `<` or `>`; combined with `when_to_use`, display truncates at 1,536 chars in the skill listing |
| `when_to_use` | No | String | Counts toward 1,536-char combined display cap | Appended to `description` in the skill listing; not a DAAF default convention |
| `metadata` | No | Dict | - | String values only |

## Unknown Fields

Unknown frontmatter fields are ignored but may cause validation errors in stricter systems. Stick to the documented fields.

**Allowed fields only:**
- `name`
- `description`
- `when_to_use`
- `metadata`

> **Legacy non-spec fields in R skills:** Some R library skills carry a top-level `autoload` field and a `metadata.tags` list from their initial port (e.g., `tidyverse`, `fixest`, `gt`). These are non-spec fields: nothing in the framework consumes them (probe quoted in the R_Support project's sessionD_05 notes, item E8). They are tolerated in existing skills but must NOT be copied into new skills.

## Complete Example

```yaml
---
name: polars
description: >-
  High-performance data manipulation with lazy/eager execution, expressions, I/O (CSV, Parquet, JSON), aggregations, joins, string/datetime ops, and pandas interop. Covers performance optimization patterns and common anti-patterns. DAAF's default DataFrame library — all pipeline code uses Polars, not pandas. Use for any DataFrame operation, reading/writing Parquet files, or migrating existing pandas code to Polars.
metadata:
  audience: research-coders
  domain: python-library
  library-version: "1.x"
---

# Polars Skill

Polars DataFrame library for high-performance data manipulation in Python.
Covers lazy/eager execution, expressions, I/O (CSV, Parquet, JSON, database),
aggregations, joins, string/datetime operations, pandas/NumPy interop, and
performance optimization. Use when working with Polars DataFrames, migrating
from pandas, reading Parquet files, or optimizing data pipeline performance.

[Rest of skill body...]
```

Note how the frontmatter description (418 chars) leads with DAAF-specific identity ("default DataFrame library — not pandas"), then covers capabilities and use triggers. The body paragraph preserves additional detail (database I/O, NumPy interop) that the description deliberately leaves out. Descriptions can run up to the 1,024-char validation limit (with the combined listing entry displaying up to 1,536 chars); use the space strategically for framework context, critical caveats, and disambiguation — not for exhaustive feature lists, which consume the shared listing budget without improving triggering.

## Description Writing Tips

### Be Specific About Triggers

```yaml
# Vague (bad)
description: Helps with data tasks.

# Specific (good)
description: Transform and analyze data with Polars. Use when working with DataFrames, CSV/Parquet files, or performing data aggregations.
```

### Include File Types When Relevant

```yaml
description: Edit and process images. Use when working with .png, .jpg, .gif files or asked to resize, crop, or convert images.
```

### Include Command/Tool Names

```yaml
description: Fast DataFrame library for Python data science. Use for any Polars data manipulation, lazy/eager execution, or performance optimization task.
```

### Front-Load Important Words

Put key information first. The skill listing caps the combined `description` + `when_to_use` text at 1,536 characters, and readers — agents scanning the listing and humans auditing it — weight the opening words most heavily. Identity and triggers belong up front.

```yaml
# Key info first (good)
description: PostgreSQL database operations. Use when writing SQL queries, managing schemas, or optimizing database performance.

# Key info buried (less good)
description: A comprehensive skill for various operations related to PostgreSQL database management and optimization.
```

### Avoid Offering Too Many Options

Provide a default approach with an escape hatch, rather than listing multiple equivalent alternatives:

```yaml
# Bad: Too many choices
description: Process PDFs using pypdf, pdfplumber, PyMuPDF, or pdf2image.

# Good: Default with escape hatch
description: Process PDFs using pdfplumber for text extraction. For scanned PDFs requiring OCR, uses pdf2image with pytesseract instead.
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall