Shared

Skill Auditor

Audits every SKILL.md in skills/ for frontmatter correctness, structural completeness, API/version drift, and cross-file reference integrity. Produces a prioritized markdown report. Read-only — never applies fixes.

When This Skill Activates

Use this skill when the user:

• Says "audit skills", "audit my skills", "run the skill auditor"
• Asks to "check the skill repo for drift", "review skills for consistency"
• Says "find broken skills", "validate skill frontmatter"
• Is planning a bulk cleanup of the skill repo
• References a specific category to audit (e.g., "audit the generators/ skills")

Does NOT activate for: creating new skills (use skill-creator), applying fixes (follow-up flow after this auditor reports), or auditing Swift code inside skills (use ios/coding-best-practices or macos/coding-best-practices).

Scope

Resolve the invocation argument in this order:

1. No argument → audit all of skills/**/SKILL.md 2. Category path (e.g., generators/, ios/) → audit skills/<arg>/**/SKILL.md 3. Single file path (e.g., skills/liquid-glass/SKILL.md) → audit one file 4. Fuzzy match → if arg doesn't resolve, try skills/<arg>/SKILL.md; fall back to asking the user

Process

1. Enumerate

Use Glob with pattern skills/**/SKILL.md from the repo root. Filter by scope if an argument was passed. Record the canonical file list — every subsequent step operates on this list.

2. Parse Frontmatter (Cached)

Read the first 15 lines of each SKILL.md. Parse:

• Whether --- frontmatter block exists
• name:, description:, allowed-tools: field values

Cache this result. Checks C-01, H-01, H-03, L-02 all read from this cache — do not re-read.

3. Run Checks

Execute bulk Grep passes in parallel (single tool-call batch) wherever possible. Per-file operations come after. The 11 checks are in the table below; the order is as-listed.

4. Classify Aggregator vs Leaf

For each file, mark it as aggregator or leaf using the rules in the "Aggregator Detection" section below. Some checks relax for aggregators.

5. Rank and Emit

Group findings by severity (🔴 → 🟢), sort within each group by file path, print the report inline using the template in "Output Format".

Checks

🔴 Critical

C-01 · Missing frontmatter. The file has no leading --- YAML block.

• Detection: multiline Grep for \A---\n[\s\S]*?\n--- across all SKILL.md. Files with no match → C-01.
• Fix: Add YAML frontmatter with name, description, allowed-tools.

🟠 High

H-01 · Missing `allowed-tools` field. Frontmatter exists but allowed-tools: key is absent.

• Detection: from cached frontmatter parse.
• Fix: Add allowed-tools: [Read, Glob, Grep] (adjust based on what the skill actually does).

H-02 · Broken supporting-file reference. The SKILL.md references a *.md file that does not exist on disk in the same directory.

• Detection: Grep each SKILL.md for [a-z0-9][a-z0-9-]*\.md matches; resolve each relative to the SKILL.md's directory; ls to confirm. Missing files → H-02. Ignore matches inside fenced code blocks.
• Fix: Create the file or remove the reference.

H-03 · H1 title does not match `name:`. The first # heading after the frontmatter, slugified (lowercase, spaces → -), differs from the name: field.

• Detection: from cached frontmatter parse + per-file line-after-frontmatter.
• Fix: Rename the H1 or the name: to match.

🟡 Medium

M-01 · Missing "When This Skill Activates" section. No ## When This Skill Activates heading anywhere in the file.

• Detection: Grep -L for ^## When This Skill Activates across all SKILL.md.
• Fix: Add section with 3–5 user trigger phrases. See shared/skill-creator/SKILL.md for the canonical format.

M-02 · Outdated version reference (drift). Mentions iOS 17–25, macOS 13–25, or Swift 5.x with drift context (treated as current/latest/target).

• Detection (two-stage):

1. Stage 1 — Grep for \biOS (1[7-9]|2[0-5])\b|\bSwift 5\.\d+\b|\bmacOS (1[3-9]|2[0-5])\b, capturing line numbers. 2. Stage 2 — for each hit, examine ±2 surrounding lines. Classify:

• Flag M-02 if surrounding lines contain: latest, newest, current, target, deployment target, requires, minimum, as of, new in, now supports, today
• Suppress if surrounding lines contain: legacy, pre-, prior to, before, deprecated, old, migrate from, backport, fallback, if available, #available, or the version mention has a trailing + (e.g., iOS 17+)
• Neither → L-03 (ambiguous)
• Known-current constants (dated 2026-04-20, update per WWDC): iOS 26, macOS 26, Swift 6.x. Mentions of these with drift context are always clean.
• Fix: Update the reference to iOS 26 / macOS 26 / Swift 6.x, or annotate as legacy context with one of the suppression keywords.

M-03 · Pre-`@Observable` pattern without deprecation callout. Uses @StateObject or ObservableObject without acknowledging that @Observable is the current pattern.

• Detection: Grep for @StateObject|ObservableObject with line numbers; for each hit, secondary Grep of the same file for @Observable|deprecated|legacy|pre-@Observable|migration|old pattern within ±10 lines. No secondary match → M-03.
• Fix: Either replace with @Observable + @State, or add a migration note explaining why the older pattern is shown.

M-04 · Oversized single-file skill. SKILL.md exceeds 400 lines and its directory contains no sibling .md files.

• Detection: wc -l via Bash on each SKILL.md; if >400, check sibling file list via ls for any other .md. None → M-04.
• Fix: Modularize — extract sections into patterns.md, templates.md, checklist.md, or examples.md per skill-creator conventions.

🟢 Low

L-01 · No ✅/❌ examples in prose. The file has no ✅ or ❌ markers anywhere.

• Detection: Grep -L for ✅|❌.
• Fix: Add at least one good/bad example pair.

L-02 · Description length out of range. description: is <20 or >300 characters.

• Detection: from cached frontmatter parse.
• Fix: Expand or shorten the description. Include a "use when…" clause to anchor activation.

L-03 · Ambiguous version mention. A version keyword matched stage 1 of the drift check but surrounding lines contained neither drift nor legacy context. User reviews manually.

• Detection: fallthrough from M-02 stage-2 classification.
• Fix: Add a drift or legacy keyword to disambiguate, or leave as-is if the context is clearly a one-off mention.

Aggregator vs Leaf Detection

A SKILL.md is an aggregator if any of the following hold:

• It sits at depth 2 under the repo root — i.e., skills/<category>/SKILL.md
• It contains the heading ## Available Modules or ## Available Skills
• It links to ./<subdir>/SKILL.md or contains two or more references of the form skills/<category>/<subskill>/

Otherwise it is a leaf.

Relaxations for aggregators

Tag every finding in the report with (aggregator) or (leaf) so severity can be read at a glance.

Output Format

Print the report inline to the conversation using this template. Use exact headings — downstream tooling may grep them.

# Skill Audit Report — <YYYY-MM-DD> — <N> files scanned

## Summary
- 🔴 Critical: <count>
- 🟠 High: <count>
- 🟡 Medium: <count>
- 🟢 Low: <count>
- ✅ Files clean: <clean-count> / <N>

Scope: <all | category | single file>

## 🔴 Critical Findings
### C-01 · Missing frontmatter
- `skills/<path>/SKILL.md` (leaf) — **Fix:** Add YAML frontmatter with `name`, `description`, `allowed-tools`.

## 🟠 High Findings
### H-01 · Missing `allowed-tools` field
- `skills/liquid-glass/SKILL.md:1-4` (leaf) — **Fix:** Add `allowed-tools: [Read, Glob, Grep]`.
- `skills/macos/macos-tahoe-apis/SKILL.md:1-4` (leaf) — **Fix:** Same.

### H-02 · Broken supporting-file reference
- `skills/<path>/SKILL.md:<line>` — references `patterns.md`, not found. **Fix:** Create the file or remove the reference.

### H-03 · H1 title does not match `name:`
- `skills/<path>/SKILL.md` — `name: foo-bar`, H1 is `# Foo Bars`. **Fix:** Rename one to match.

## 🟡 Medium Findings
### M-01 · Missing "When This Skill Activates" section (<count>)
- `skills/design/liquid-glass/SKILL.md` (leaf)
- `skills/macos/coding-best-practices/SKILL.md` (leaf)
- [collapsed list of remaining offenders]
- **Fix:** Add section with 3–5 user trigger phrases.

### M-02 · Outdated version reference (<count>)
- `skills/<path>/SKILL.md:87` (leaf) — "latest iOS 17" in drift context. **Fix:** Update to iOS 26.

### M-03 · Pre-`@Observable` pattern without callout (<count>)
- `skills/<path>/SKILL.md:142` (leaf) — `@StateObject` without migration note. **Fix:** Replace with `@Observable` or add callout.

### M-04 · Oversized single-file skill (<count>)
- `skills/<path>/SKILL.md` — <NNN> lines, no sibling .md files. **Fix:** Modularize into `patterns.md` / `templates.md`.

## 🟢 Low Findings
### L-01 · No ✅/❌ examples
- `skills/<path>/SKILL.md` (leaf) — **Fix:** Add at least one good/bad example pair.

### L-02 · Description length out of range
- `skills/<path>/SKILL.md` — description is <N> chars. **Fix:** Expand/shorten to 20–300 chars.

### L-03 · Ambiguous version mention
- `skills/<path>/SKILL.md:<line>` — "iOS 18" with no drift/legacy context. **Fix:** Review manually.

## ✅ Clean Files
<collapsed list of files that passed all checks>

## Next Steps
- Review 🔴/🟠 findings first — they block skills from working as intended.
- Batch-fix 🟡 M-01 and M-02 mechanically — suggested find/replace scripts shown per-file.
- 🟢 findings are polish; address opportunistically.

Implementation Notes

• Parallelize bulk Greps in a single tool-call batch where possible. Activation, frontmatter, @StateObject, and drift-stage-1 can all run at once.
• Cache the frontmatter parse. Four checks read it; only parse once.
• *Resolve `.md` references inside fenced code blocks carefully** — they're examples, not references. Strip fenced blocks before running H-02's regex.
• Progress pings — for full-repo scans (148 files), emit a short "scanning <N>/<total>…" before each phase so the user sees liveness.
• Idempotence — the report body (everything below the ## Summary) should be deterministic for a given repo state. Only the date in the H1 varies across runs.
• Never write files. This skill's allowed-tools lists Bash, but only for read-only ops (wc, ls). If you find yourself needing to write, stop and ask the user to invoke a fix flow separately.

Non-Goals

• No auto-fix. The report includes one-line fix suggestions per finding; applying them is a separate user-initiated task.
• No network calls. This auditor does not verify URL liveness or check Apple doc availability.
• No Swift compilation. Code-block validity is beyond scope; patterns are matched textually.
• No WWDC session cross-referencing. A future wwdc-to-skill-workflow skill owns that.

Maintenance

The drift heuristic hardcodes "known-current" version constants:

• iOS 26, macOS 26, Swift 6.x (dated 2026-04-20)

Update these constants when Apple ships a new major platform version (usually post-WWDC each June). The stage-1 regex ranges (iOS 1[7-9]|2[0-5], macOS 1[3-9]|2[0-5]) must also be widened to include the newly-retired version.

Verification

After running the auditor on the full repo, counts should fall within this tolerance band (baseline taken 2026-04-20, 149 total SKILL.md files):

Known legacy pattern: ## When to Use

The 9 C-01 offenders all use ## When to Use (non-canonical) rather than ## When This Skill Activates. The auditor flags this as M-01 correctly; the suggested fix is to rename the heading when adding frontmatter. Do not widen the M-01 regex to accept ## When to Use — the whole point is to normalize onto the canonical heading.

Smoke tests

1. Full-repo run — invoke with no arg. Counts must fall within tolerance above. 2. Scoped run — invoke with generators/. Only skills/generators/** paths appear. 3. Single-file run — invoke with skills/liquid-glass/SKILL.md. Report has exactly one H-01 finding. 4. Idempotence — re-run immediately. Report body is byte-identical; only the date in the H1 may differ. 5. Drift heuristic sanity — spot-check 5 M-02 hits and 5 suppressed legacy mentions. If any legacy mention is mis-flagged, extend the suppression keyword list and re-run.

References

• /Users/ravishankar/Work/MyApps/claude-code-apple-skills/CLAUDE.md — normative source for frontmatter schema, naming, emoji convention
• skills/shared/skill-creator/SKILL.md — companion meta-skill for creating new skills (this auditor only audits; it does not create)
• skills/ios/SKILL.md — canonical aggregator example

Complex Skill Template

Template for creating modularized skills with supporting reference files.

When to Use This Template

Use for complex skills that:

• ✅ Have extensive checklists (50+ items)
• ✅ Cover multiple distinct topics
• ✅ Include lots of code examples
• ✅ Need comprehensive reference material
• ✅ Would exceed 400-500 lines in a single file

Recommended Structure

.claude/skills/skill-name/
├── SKILL.md                    # Main skill definition (200-300 lines)
├── checklist.md               # Comprehensive checklists
├── patterns.md                # Code patterns and anti-patterns
├── examples.md                # Extensive code examples
├── quick-ref.md               # Quick reference guide
└── guidelines.md              # Detailed guidelines

Main SKILL.md Template

---
name: skill-name
description: Brief description of what the skill does and when to use it
allowed-tools: [Read, Write, Edit, Glob, Grep]
---

# Skill Name

One-paragraph description of the skill's purpose and capabilities.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]
- [Additional triggers as needed]

## Review Process

### 1. Identify Scope

- How to determine what to review
- What to prioritize
- Scope clarification steps

### 2. Load Reference Materials

Before starting, familiarize yourself with these references in `.claude/skills/skill-name/`:

- **patterns.md** - Common patterns and anti-patterns
- **checklist.md** - Comprehensive review checklist
- **examples.md** - Code examples and templates
- **quick-ref.md** - Quick reference for common issues
- **guidelines.md** - Detailed guidelines and standards

### 3. Review Categories

Apply these review categories:

**Category 1:**
- High-level checks
- What to look for
- Key considerations

**Category 2:**
- Another set of checks
- Related concerns
- Important patterns

**Category 3:**
- Additional checks
- Special cases
- Edge cases

### 4. Output Format

Present findings in this structure:

#### ✅ Strengths Found
- [List well-implemented patterns]
- [Highlight good practices]

#### ⚠️ Issues Found

**Category: [Category Name]**

**[Priority]: [File:Line]** - [Description]

// Current code [problematic code]

// Suggested fix [improved code]

// Reason: [explanation]

#### 📊 Quality Score

**Overall: X/10**

- Category 1: X/10
- Category 2: X/10
- Category 3: X/10

#### 📋 Recommendations

1. **High Priority**: [Critical issues]
2. **Medium Priority**: [Improvements]
3. **Low Priority**: [Nice-to-haves]

#### 🔧 Quick Wins

List 3-5 easy fixes that provide immediate value

## Quick Reference Checklist

Brief, high-level checklist for quick validation:

### Essential Checks
- [ ] Critical item 1
- [ ] Critical item 2
- [ ] Critical item 3

(Full checklist available in checklist.md)

## Tips for Effective Reviews

### Be Constructive
- Provide examples
- Explain reasoning
- Be educational

### Consider Context
- Some patterns have valid uses
- Balance idealism with pragmatism
- Consider project constraints

### Prioritize Impact
- Correctness first
- Performance second
- Style last

## References

- [External documentation link]
- [Related resource link]
- Supporting files in this skill directory

## Notes

- Important considerations
- Known limitations
- Future enhancements

patterns.md Template

# Patterns and Anti-Patterns

Common patterns and anti-patterns for [skill topic].

## Category 1

### Anti-patterns

// ❌ Bad - [Why it's bad] [problematic code example]

// ❌ Bad - [Another reason] [another bad example]

### Good Patterns

// ✅ Good - [Why it's good] [good code example]

// ✅ Good - [Another good pattern] [another good example]

### When to Use

- [Scenario 1]
- [Scenario 2]
- [Scenario 3]

### When to Avoid

- [Scenario where pattern doesn't apply]
- [Edge case to watch for]

## Category 2

[Repeat structure for each category]

## Pattern Comparison Table

| Pattern | Use When | Avoid When | Complexity |
|---------|----------|------------|------------|
| Pattern A | [Use case] | [Avoid case] | Low |
| Pattern B | [Use case] | [Avoid case] | Medium |
| Pattern C | [Use case] | [Avoid case] | High |

## References

- [Pattern documentation]
- [Best practices guide]

checklist.md Template

# Comprehensive Checklist

Detailed checklist for [skill topic] review.

## Category 1

### Subcategory 1.1
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

### Subcategory 1.2
- [ ] Check item 4
- [ ] Check item 5
- [ ] Check item 6

## Category 2

### Subcategory 2.1
- [ ] Check item 7
- [ ] Check item 8
- [ ] Check item 9

### Subcategory 2.2
- [ ] Check item 10
- [ ] Check item 11
- [ ] Check item 12

## Category 3

[Continue with additional categories]

## Priority Matrix

| Priority | Category | Items |
|----------|----------|-------|
| High | [Category] | [Item numbers] |
| Medium | [Category] | [Item numbers] |
| Low | [Category] | [Item numbers] |

## Quick Check

Essential items to always verify:
- [ ] Critical item 1
- [ ] Critical item 2
- [ ] Critical item 3

examples.md Template

# Code Examples and Templates

Comprehensive examples for [skill topic].

## Example 1: [Scenario Name]

### Description
What this example demonstrates and when to use it.

### Before (Anti-pattern)

// ❌ Problematic code [bad code example]

**Problems:**
- [Issue 1]
- [Issue 2]
- [Issue 3]

### After (Good Pattern)

// ✅ Improved code [good code example]

**Improvements:**
- [Improvement 1]
- [Improvement 2]
- [Improvement 3]

### Why It Matters
[Explanation of impact and benefits]

## Example 2: [Another Scenario]

[Repeat structure]

## Templates

### Template 1: [Template Name]

// Template for [purpose] [code template with placeholders]

**Usage:**
1. Replace [placeholder1] with [description]
2. Replace [placeholder2] with [description]
3. [Additional steps]

### Template 2: [Another Template]

[Repeat structure]

## Real-World Examples

### Example from [Project/Context]

[Complete, realistic example with full context]

[full code example]

**Analysis:**
- [What's good]
- [What could be improved]
- [Lessons learned]

quick-ref.md Template

# Quick Reference

Fast lookup guide for common [skill topic] issues and solutions.

## Common Issues

### Issue 1: [Issue Name]

**Problem:**

[problematic code]

**Solution:**

[fixed code]

**Quick Fix:** [One-line explanation]

### Issue 2: [Another Issue]

[Repeat structure]

## Common Patterns

### Pattern 1: [Pattern Name]

**When:** [When to use]

**Code:**

[pattern code]

**Note:** [Important consideration]

## Command Reference

| Command/Syntax | Description | Example |
|----------------|-------------|---------|
| [Syntax 1] | [What it does] | `[example]` |
| [Syntax 2] | [What it does] | `[example]` |

## Keyboard Shortcuts

| Action | Shortcut | Notes |
|--------|----------|-------|
| [Action 1] | [Keys] | [When to use] |
| [Action 2] | [Keys] | [When to use] |

## Decision Trees

### When to use Pattern A vs Pattern B

Start ├─ Need [Feature X]? │ ├─ Yes → Use Pattern A │ └─ No → Continue └─ Need [Feature Y]? ├─ Yes → Use Pattern B └─ No → Use default

## Resources

- [Quick link 1]
- [Quick link 2]

guidelines.md Template

# Detailed Guidelines

Comprehensive guidelines for [skill topic].

## Philosophy

Core principles behind these guidelines:
1. [Principle 1]
2. [Principle 2]
3. [Principle 3]

## Category 1: [Category Name]

### Overview
What this category covers and why it matters.

### Guidelines

#### Guideline 1.1: [Guideline Name]

**Description:**
Detailed explanation of the guideline.

**Rationale:**
Why this guideline exists and what problems it solves.

**Examples:**

// ❌ Violates guideline [bad example]

// ✅ Follows guideline [good example]

**Exceptions:**
- [Scenario where exception is valid]
- [Another valid exception]

#### Guideline 1.2: [Another Guideline]

[Repeat structure]

## Category 2: [Another Category]

[Repeat structure]

## Best Practices Summary

### Must Do (Critical)
- [Critical practice 1]
- [Critical practice 2]

### Should Do (Recommended)
- [Recommended practice 1]
- [Recommended practice 2]

### Could Do (Optional)
- [Optional practice 1]
- [Optional practice 2]

## Anti-Patterns to Avoid

### Anti-Pattern 1: [Name]

**Description:** [What it is]

**Why Avoid:** [Problems it causes]

**Better Approach:** [What to do instead]

## Decision Guidelines

### When to Choose Option A
- [Criterion 1]
- [Criterion 2]

### When to Choose Option B
- [Criterion 1]
- [Criterion 2]

## References

- [Authoritative source 1]
- [Best practices documentation]
- [Style guide reference]

Modularization Strategy

Step 1: Identify Topics

Break down your skill into logical topics:

• Core concepts
• Patterns and practices
• Examples and templates
• Reference materials
• Guidelines and standards

Step 2: Assign Files

Map topics to files:

• Main logic → SKILL.md
• Comprehensive lists → checklist.md
• Code patterns → patterns.md
• Examples → examples.md
• Quick lookup → quick-ref.md
• Detailed rules → guidelines.md

Step 3: Cross-Reference

In SKILL.md, reference supporting files:

### 2. Load Reference Materials

Before starting, read:
- **patterns.md** - [Brief description]
- **checklist.md** - [Brief description]

Step 4: Keep SKILL.md Lean

Main SKILL.md should be:

• 200-300 lines ideally
• High-level process and workflow
• References to detailed materials
• Essential checklists only
• Output format definition

File Size Guidelines

Testing Your Complex Skill

1. Verify structure: All referenced files exist 2. Check links: References are accurate 3. Test workflow: Follow process end-to-end 4. Validate output: Output format works as expected 5. Review modularization: Information is well-organized

Example: Existing Complex Skills

See these skills for reference:

• coding-best-practices - Well-modularized code review skill
• ui-review - UI/accessibility review with references

Tips

• Start with basic template, modularize when needed
• Keep each file focused on one topic
• Use consistent formatting across files
• Cross-reference related information
• Update all files when changing structure
• Test after major refactoring

References

• [Claude Code Skills Documentation]
• Example skills in .claude/skills/

Basic Skill Template

Template for creating simple, self-contained skills.

Template Structure

---
name: skill-name
description: Brief description of what the skill does and when to use it. Keep it to 1-2 sentences that clearly explain the purpose.
allowed-tools: [Read, Write, Edit]
---

# Skill Name

One-paragraph description of what this skill does and its primary purpose.

## When This Skill Activates

Use this skill when the user:
- [Specific trigger phrase or action 1]
- [Specific trigger phrase or action 2]
- [Specific trigger phrase or action 3]
- [Additional triggers as needed]

## Process

### 1. [First Step Name]

- Clear instruction about what to do first
- What to check or verify
- Expected outcomes or decisions

### 2. [Second Step Name]

- Instructions for the second step
- What data to gather or analyze
- How to process the information

### 3. [Third Step Name]

- Instructions for the third step
- How to synthesize findings
- What to prepare for output

### 4. Output Format

How to present results to the user:

#### [Section 1 Name]
- Format for first section
- What information to include

#### [Section 2 Name]
- Format for second section
- Structure and content

#### [Section 3 Name]
- Format for third section
- Final recommendations or next steps

## Checklist

Use this checklist to ensure completeness:

### [Category 1]
- [ ] Check item 1
- [ ] Check item 2
- [ ] Check item 3

### [Category 2]
- [ ] Check item 4
- [ ] Check item 5
- [ ] Check item 6

## Examples

### Example 1: [Scenario Name]

**Input:**

[Example input or code]

**Expected Output:**

[Example output format]

### Example 2: [Another Scenario]

**Input:**

[Another example]

**Expected Output:**

[Corresponding output]

## Tips

- [Helpful tip 1]
- [Helpful tip 2]
- [Best practice 1]
- [Best practice 2]

## References

- [Link to relevant documentation]
- [Link to related resources]
- [Internal file references if any]

## Notes

- Additional context or considerations
- Edge cases to be aware of
- Limitations of the skill

Fill-In Guide

When using this template:

name

Use kebab-case (lowercase with hyphens):

• ✅ code-reviewer
• ✅ test-generator
• ❌ CodeReviewer
• ❌ code_reviewer

description

Keep it concise (1-2 sentences):

• Start with what the skill does
• End with when to use it
• Example: "Reviews Swift/iOS code for best practices and common issues. Use when performing code quality checks or refactoring."

allowed-tools

Choose appropriate tools:

• Read-only: [Read, Glob, Grep]
• Code changes: [Read, Write, Edit]
• Full access: [Read, Write, Edit, Glob, Grep, Bash]
• Web research: [Read, WebFetch]

When This Skill Activates

List specific phrases or situations:

• User says "review my code"
• User mentions "best practices"
• User asks "how can I improve this?"

Process Steps

Break down the workflow: 1. What to do first 2. What to do second 3. How to synthesize 4. How to output

Checklist

Create actionable items:

• Each item should be verifiable
• Group related items
• Use clear, specific language

Examples

Provide concrete examples:

• Show input and output
• Use realistic scenarios
• Cover common use cases

When to Use This Template

Use the basic skill template when:

• ✅ Skill has a single, focused purpose
• ✅ Process can be described in <400 lines
• ✅ No extensive reference material needed
• ✅ Examples fit within the main file
• ✅ Checklist is concise

Don't use when:

• ❌ Skill needs extensive checklists (>50 items)
• ❌ Multiple distinct topics/categories
• ❌ Lots of code examples
• ❌ Complex reference material

For complex skills, use the complex-skill-template.md instead.

Example Usage

Here's a filled-out example:

---
name: function-documenter
description: Generates comprehensive documentation for Swift functions including parameter descriptions, return values, and usage examples. Use when documenting code or improving API documentation.
allowed-tools: [Read, Write, Edit]
---

# Function Documenter

Automatically generates comprehensive documentation for Swift functions.

## When This Skill Activates

Use this skill when the user:
- Asks to "document this function"
- Mentions "add documentation"
- Requests "generate docs for this code"
- Wants to improve API documentation

## Process

### 1. Analyze Function Signature

- Read the function signature
- Identify all parameters and their types
- Determine return type
- Note any throws/async keywords

### 2. Understand Functionality

- Read function implementation
- Identify the primary purpose
- Note any side effects
- Understand error conditions

### 3. Generate Documentation

- Write clear summary line
- Document each parameter
- Describe return value
- Note any errors thrown
- Add usage example

### 4. Output Format

Generate documentation in this format:

/// [One-line summary of what the function does] /// /// [Detailed description if needed] /// /// - Parameters: /// - parameter1: Description of parameter1 /// - parameter2: Description of parameter2 /// - Returns: Description of what is returned /// - Throws: Description of errors that can be thrown /// /// Example: /// ``swift /// let result = functionName(parameter1: value1, parameter2: value2) /// `` func functionName(parameter1: Type1, parameter2: Type2) throws -> ReturnType { // implementation }

## Checklist

### Documentation Completeness
- [ ] One-line summary present
- [ ] All parameters documented
- [ ] Return value described
- [ ] Errors documented (if throws)
- [ ] Usage example provided

### Quality Checks
- [ ] Summary is clear and concise
- [ ] Parameter descriptions explain purpose, not just type
- [ ] Example is runnable and realistic
- [ ] Documentation uses proper markdown formatting

## Example

### Input Function

func calculateTotal(items: [Item], discount: Double) throws -> Double { guard !items.isEmpty else { throw CalculationError.emptyCart } let subtotal = items.reduce(0) { $0 + $1.price } return subtotal * (1 - discount) }

### Generated Documentation

/// Calculates the total cost of items after applying a discount. /// /// Sums up the prices of all items and applies the discount percentage /// to calculate the final total. /// /// - Parameters: /// - items: The items to calculate the total for. Must not be empty. /// - discount: The discount to apply, as a decimal (e.g., 0.1 for 10%) /// - Returns: The total cost after discount /// - Throws: CalculationError.emptyCart if items array is empty /// /// Example: /// ``swift /// let items = [Item(price: 10.0), Item(price: 20.0)] /// let total = try calculateTotal(items: items, discount: 0.1) /// // total = 27.0 (30.0 - 10%) /// `` func calculateTotal(items: [Item], discount: Double) throws -> Double { guard !items.isEmpty else { throw CalculationError.emptyCart } let subtotal = items.reduce(0) { $0 + $1.price } return subtotal * (1 - discount) }

## Tips

- Keep summary line under 80 characters
- Use imperative mood ("Calculates..." not "This calculates...")
- Provide meaningful examples, not just syntax
- Document what, not how (implementation is visible)

## References

- [Swift Documentation Markup](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/)

## Notes

- For complex functions, break down the description into sections
- Include edge cases in examples
- Update documentation when function signature changes