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/gotchas.md

View on GitHub
# Gotchas & Best Practices

Common mistakes, validation errors, and a pre-submission checklist for skill authors.

## Validation Errors

### "SKILL.md not found"

**Cause:** File doesn't exist or wrong location.

**Fix:**
```bash
# Check file exists
ls .claude/skills/my-skill/SKILL.md

# Check spelling (must be uppercase)
# SKILL.md ✓
# skill.md ✗
# Skill.md ✗
```

### "No YAML frontmatter found"

**Cause:** File doesn't start with `---`.

**Fix:** Ensure frontmatter starts on line 1:
```yaml
---
name: my-skill
description: ...
---
```

Not:
```markdown
# My Skill
---
name: my-skill
```

### "Invalid frontmatter format"

**Cause:** Frontmatter not properly delimited.

**Fix:** Check for matching `---` markers:
```yaml
---
name: my-skill
description: My description.
---

# Content starts here
```

### "Invalid YAML in frontmatter"

**Cause:** YAML syntax error.

**Common issues:**

| Problem | Invalid | Valid |
|---------|---------|-------|
| Unquoted special chars | `description: Use <this>` | `description: "Use this"` |
| Missing colon | `name my-skill` | `name: my-skill` |
| Bad indentation | Mixed tabs/spaces | Consistent spaces |
| Unescaped quotes | `description: Say "hello"` | `description: 'Say "hello"'` |

### "Missing 'name' in frontmatter"

**Cause:** Required `name` field absent.

**Fix:**
```yaml
---
name: my-skill
description: ...
---
```

### "Missing 'description' in frontmatter"

**Cause:** Required `description` field absent.

**Fix:**
```yaml
---
name: my-skill
description: What this does. When to use it.
---
```

### "Name must be hyphen-case"

**Cause:** Invalid characters in name.

| Invalid | Issue | Valid |
|---------|-------|-------|
| `My-Skill` | Uppercase | `my-skill` |
| `my_skill` | Underscore | `my-skill` |
| `my skill` | Space | `my-skill` |
| `-my-skill` | Leading hyphen | `my-skill` |
| `my-skill-` | Trailing hyphen | `my-skill` |
| `my--skill` | Consecutive hyphens | `my-skill` |

### "Name is too long"

**Cause:** Name exceeds 64 characters.

**Fix:** Shorten the name. Use abbreviations if needed.

### "Description cannot contain angle brackets"

**Cause:** `<` or `>` in description.

**Fix:**
```yaml
# Invalid
description: Use <command> to do X.

# Valid
description: Use the command to do X.
```

### "Description is too long"

**Cause:** Description exceeds 1024 characters.

**Fix:** Shorten description. Move details to SKILL.md body.

### "Unexpected key(s) in frontmatter"

**Cause:** Unknown fields in frontmatter.

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

**Invalid fields (examples):**
- `author`
- `version`
- `tags`
- `short-description`

### "Directory name doesn't match skill name"

**Cause:** Folder name differs from `name` field.

**Fix:**
```
# Must match
.claude/skills/my-skill/SKILL.md
               ^^^^^^^^
---
name: my-skill
      ^^^^^^^^
---
```

## Common Anti-Patterns

### "When to Use" in Body

**Problem:** Triggering info in body, loaded too late.

```markdown
---
name: my-skill
description: A helpful skill.
---

## When to Use This Skill  <!-- WRONG: This is never seen during triggering -->

Use this when you need to...
```

**Fix:** Put triggering info in `description`:

```yaml
description: A helpful skill. Use when you need to process PDFs or manipulate documents.
```

### Undertriggering

**Problem:** Skill doesn't load when it should. Users have to manually enable it.

**Symptoms:**
- Skill never loads automatically
- Users manually invoking it by name
- Support questions about when to use it

**Diagnosis:** Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back. Adjust based on what's missing.

**Fix:** Make the description more "pushy" — include contexts where the skill should activate even without explicit naming:

```yaml
# Before (undertriggers)
description: Build dashboards to display data.

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

### Overtriggering

**Problem:** Skill loads for unrelated queries. Users disabling it.

**Symptoms:**
- Skill loads for clearly unrelated tasks
- Users confused about why it activated
- Interference with other skills

**Fix:** Add negative triggers and narrow scope:

```yaml
# Before (overtriggers)
description: Processes documents.

# After (narrowed scope)
description: Processes PDF legal documents for contract review. Do NOT use for general document editing, spreadsheets, or non-PDF formats.
```

### Overly Verbose Descriptions

**Problem:** Rambling, low-information-density prose. The issue is not length per se — a complete 300-700 char description is good, and descriptions may run up to the 1,024-char validation limit. The issue is padding: filler phrasing that consumes the aggregate skill-listing budget (shared across 40+ DAAF skills) without improving triggering accuracy.

```yaml
# Bad: padded — many words, few triggers, no disambiguation
description: This skill is a comprehensive solution for managing and processing various types of document files including but not limited to PDF, Word, and Excel formats. It provides functionality for...
```

**Fix:** Spend characters where they earn triggering accuracy — identity, key triggers, disambiguation, critical caveats:

```yaml
# Good: information-dense — every clause earns its place
description: Process document files (PDF, Word, Excel) — converting formats, extracting text and tables, merging/splitting, and manipulating document content. Use when working with .pdf, .docx, or .xlsx files, or when asked to pull structured data out of documents. For plain-text or Markdown editing, use standard file tools instead; for scanned documents requiring OCR, use the ocr skill.
```

### Duplicated Content

**Problem:** Same info in SKILL.md and references.

**Fix:** Information lives in ONE place. Reference it from other locations.

### Nested References

**Problem:** Multi-level reference directories.

```
# Bad
references/
├── api/
│   ├── endpoints.md
│   └── auth.md
└── guides/
    └── quickstart.md

# Good
references/
├── api-endpoints.md
├── api-auth.md
└── quickstart.md
```

### Giant SKILL.md

**Problem:** 800+ line SKILL.md file.

**Fix:** Split into references. Keep SKILL.md as navigation hub (<500 lines). Note: the opposite problem — *anemic reference files* — is equally harmful. Reference files should be comprehensive since they load on-demand. Aim for total reference content >= 3x SKILL.md lines for data source skills.

### Missing Decision Trees

**Problem:** No navigation for complex skills.

**Fix:** Add decision trees pointing to relevant sections/files.

### No Topic Index

**Problem:** Hard to find specific topics.

**Fix:** Add Topic Index table at end of SKILL.md.

### Untested Scripts

**Problem:** Scripts that don't work.

**Fix:** Test all scripts manually before including:

```bash
python ./scripts/my_script.py --help
python ./scripts/my_script.py test-input.txt
```

### Too Many Options

**Problem:** Presenting multiple equivalent approaches instead of a clear default.

**Fix:** Provide one recommended approach with an escape hatch:

```markdown
# Bad: Confusing choices
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

# Good: Default with escape hatch
Use pdfplumber for text extraction. For scanned PDFs requiring OCR,
use pdf2image with pytesseract instead.
```

### Windows-Style Paths

**Problem:** Using backslashes in file paths, which fail on Unix systems.

**Fix:** Always use forward slashes — they work cross-platform:

```markdown
# Bad
scripts\helper.py
reference\guide.md

# Good
scripts/helper.py
reference/guide.md
```

### Unnecessary Files

**Problem:** README.md, CHANGELOG.md, etc.

Skills are for AI execution, not human documentation.

**Don't include:**
- README.md
- INSTALLATION_GUIDE.md
- CHANGELOG.md
- CONTRIBUTING.md
- LICENSE

### Reference Files Named `report*`, `summary*`, `findings*`, `analysis*`

**Problem:** Skills are often written by a subagent (framework-engineer, or a `general-purpose` agent in Data Onboarding), and on Claude Code 2.1.281 (observed 2026-10-19) the Write tool rejects any subagent Write to a `.md` basename starting with `report`, `summary`, `findings` or `analysis`, in any case, before any hook runs. The prefix match also catches ordinary words: `reporting.md`, `analysis-patterns.md`, `summary-statistics.md`. Such a file cannot be created with Write, or rewritten in full with Write, by a subagent. Edit of an existing file still works; creating the file with Edit or a shell write instead is routing around the check, not a fix. See CLAUDE.md § Project Conventions > Subagent File Output.

**Fix:** Name new reference files so the basename starts with another word: `model-reporting.md`, `patterns-for-analysis.md`, `descriptive-statistics.md`. Four existing files already match and are **Edit-only** for subagents: `agent_reference/REPORT_TEMPLATE.md`, `.claude/agents/report-writer.md`, `.claude/skills/fixest/references/reporting.md`, `.claude/skills/r-stats/references/reporting.md`.

### Library Skill Version Drift

**Problem (library/tool skills):** The skill pins a version that was never published to the package index, or documents an API that differs from the build actually installed in the container. Both look authoritative but mislead — `pip install pkg==X.Y` fails because the GitHub release tag has no corresponding published package, or a documented function signature does not exist in the installed build because upstream docs describe a newer API than what is installed.

**Fix — verify against the package index and the installed build before authoring:**

- **Confirm installability before pinning.** A GitHub release tag can exist with no published package. Probe the index (PyPI / CRAN) rather than trusting the tag. (Note: CRAN's index exposes only each package's *current* version — `available.packages()` cannot confirm an older version, which lives in the CRAN archive.)
  ```bash
  pip index versions <pkg>                          # available published versions (read-only)
  # R: "<pkg>" %in% rownames(available.packages())  # package present on CRAN?
  #    available.packages()["<pkg>", "Version"]     # its current CRAN version, to compare
  ```
- **Introspect the installed build before writing against upstream docs.** The container's installed build is the ground truth the skill must describe. Confirm the version and the actual signatures you document:
  ```bash
  pip show <pkg>                          # installed version (read-only)
  python -c "import importlib.metadata as m; print(m.version('<pkg>'))"
  # R: packageVersion("<pkg>"); args(<fn>)
  ```

## Pre-Submission Checklist

### Frontmatter

- [ ] `name` is lowercase hyphen-case
- [ ] `name` matches directory name
- [ ] `name` is 1-64 characters
- [ ] `description` includes what skill does
- [ ] `description` includes when to use it (triggers)
- [ ] `description` is 1-1024 characters
- [ ] `description` has no angle brackets
- [ ] No unknown frontmatter fields

### Structure

- [ ] SKILL.md is under 500 lines
- [ ] Has "What is X?" or equivalent intro
- [ ] Has decision trees for navigation (if complex)
- [ ] Has Quick Reference section
- [ ] Has Topic Index (if has references)
- [ ] Reference files are one level deep
- [ ] Long references (>100 lines) have TOC
- [ ] All file paths use forward slashes (no backslashes)

### Content

- [ ] Uses imperative/infinitive form
- [ ] Prefers examples over prose
- [ ] No duplicated information
- [ ] No "When to Use" section in body
- [ ] Code blocks have language specified
- [ ] Tables used for quick lookups
- [ ] Consistent terminology throughout (one term per concept)
- [ ] Describes the current release: no change stories about DAAF; only the data's own history or a short fenced "recognizing older forms" note (`agent_reference/DOCUMENTATION_STANDARDS.md` § S5 Current State)
- [ ] Cites only files that ship and public URLs: no `research/` workspace, scratch or maintainer-local paths (§ S4 Self-Contained)
- [ ] Dated stamps only on facts that change outside DAAF (Claude Code versions, models, vendor APIs); none on DAAF's own behavior (§ Dated Stamps)
- [ ] Triage lint run and each hit in the skill's files reviewed: `bash /daaf/tests/lint/docs-triage.sh --untracked` (§ The Triage Lint)
- [ ] Explains "why" behind instructions, not just "what"

### Resources (if applicable)

- [ ] Scripts tested and working
- [ ] Scripts have clear parameters
- [ ] References are focused (one topic each)
- [ ] Assets are necessary and minimal
- [ ] Resources documented in SKILL.md
- [ ] Scripts handle errors explicitly (don't punt to Claude)
- [ ] Script constants are documented (no magic numbers)
- [ ] Execute vs. read intent is clear for each script

### Files

- [ ] No README.md
- [ ] No CHANGELOG.md
- [ ] No auxiliary documentation
- [ ] Only necessary files included
- [ ] No new `.md` file whose name starts with `report`, `summary`, `findings` or `analysis` (a subagent cannot Write it)

### Testing

- [ ] 2-3 realistic test prompts created
- [ ] Triggering tested (should-trigger and should-not-trigger queries)
- [ ] Tested with real usage scenarios
- [ ] Iterated based on observed behavior

## Self-Review Questions

Before finalizing, ask:

1. **Triggering:** Will the description match user queries that should trigger this skill?

2. **Completeness:** Does the skill contain everything needed to accomplish its purpose?

3. **Conciseness (SKILL.md):** Does every line in SKILL.md justify its token cost? (Reference files have different economics — thoroughness is preferred; see `progressive-disclosure.md`.)

4. **Navigation:** Can users quickly find what they need?

5. **Examples:** Are there enough examples to guide usage?

6. **Testing:** Have all scripts been tested?

7. **Duplication:** Is any information repeated?

8. **Scope:** Is the skill focused on one domain/purpose?

## Quick Fixes

| Problem | Quick Fix |
|---------|-----------|
| Skill not triggering | Improve `description` with specific triggers |
| Too long | Split into references |
| Hard to navigate | Add decision trees |
| Missing info | Add to appropriate reference file |
| Script failing | Test script, check paths |
| Validation error | Check frontmatter format |
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