Skill Writer Skill | Agent Skills

Skill Writer

Expert guide for creating SKILL.md skills.

Compatibility Note

This pi wrapper preserves the original skill authoring target. The wrapper only adapts invocation to pi; it does not retarget the generated skill format.

Purpose

Generate precise SKILL.md files that comply with the target skill specification:

Validate naming constraints (64 chars, lowercase/numbers/hyphens only, no reserved words)
Enforce description requirements (1024 chars max, third person, trigger keywords)
Apply tool minimalism (only grant necessary tools)
Ensure project-agnostic field is explicitly set
Maintain file structure constraints (under 500 lines, one-level references)

Variables

None - skill-writer has no runtime configuration.

Instructions

1. Understand Request

Parse user request to determine:

Skill purpose and scope
Target operations (read-only, write, refactor, workflow)
Project-specific vs reusable

2. Validate Constraints (BLOCKING)

STOP. Validate BEFORE generating.

| Field | Constraint | |-------|------------| | name | Max 64 chars, /^[a-z0-9-]+$/, no "anthropic"/"claude" | | description | Max 1024 chars, third person, includes "Triggers on keywords:" | | project-agnostic | REQUIRED - must be explicitly true or false |

Frontmatter quoting rule:

Wrap description in double quotes in YAML frontmatter.
Wrap any other frontmatter string field in double quotes too when it contains YAML-significant or syntax-looking content, such as :, [], {}, #, &, *, ?, |, >, @, backticks, or leading/trailing whitespace.

See cookbook/validation.md for detailed checks.

3. Select Pattern

Choose from templates/:

skill-template.md - Comprehensive template with all sections

4. Generate SKILL.md

Apply template with validated values. Follow structure from templates/skill-template.md.

5. Verify (BLOCKING)

STOP. Verify before delivery.

Line count under 500
description is wrapped in double quotes in YAML frontmatter
Any other YAML-sensitive frontmatter string values are double-quoted
No bash execution pattern (exclamation-backtick sequence)
All paths use forward slashes
References are one-level deep

Workflow

1. Parse request -> scope, tools, agnostic?
2. Validate constraints -> BLOCK if invalid
3. Select pattern based on tool needs
4. Generate SKILL.md from template
5. Verify output -> BLOCK if violations
6. Deliver with checklist confirmation

Report

Output format for generated skills:

## Generated Skill: {name}

### Validation
- Name: PASS/FAIL (reason)
- Description: PASS/FAIL (reason)
- Project-agnostic: PASS/FAIL (value)
- Tools: {count} tools granted

### Files Created
- SKILL.md ({line_count} lines)
- {supporting_files if any}

### Checklist
- [ ] Name constraints satisfied
- [ ] Description includes triggers
- [ ] project-agnostic explicitly set
- [ ] Under 500 lines
- [ ] Minimal tools granted

Examples

DOs

Focused purpose with minimal tools:

---
name: python-type-annotator
description: "Adds type annotations to Python functions. Infers types from usage and docstrings. Triggers on keywords: add types, type hints, annotate python"
project-agnostic: true
allowed-tools:
  - Read
  - Edit
  - Glob
---

Clear triggers in description:

description: "Formats SQL queries with consistent style. Handles SELECT, INSERT, UPDATE, DELETE. Triggers on keywords: format sql, sql formatter, pretty print sql"

Explicit project-agnostic for reusable skills:

project-agnostic: true  # Zero project dependencies

DONTs

Vague name and description:

# BAD - unfocused
name: code-helper
description: "Helps with all coding tasks"

Missing trigger keywords:

# BAD - not discoverable
description: "Formats SQL queries"

Excessive tool permissions:

# BAD - grants more than needed for read-only task
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

Missing project-agnostic:

# BAD - required field missing
name: my-skill
description: "Does something"
allowed-tools:
  - Read

Reserved word in name:

# BAD - contains reserved word
name: claude-assistant

Quick Reference

YAML Frontmatter Template

---
name: skill-name
description: "Third-person description under 1024 chars. Triggers on keywords: keyword1, keyword2"
project-agnostic: true
allowed-tools:
  - Read
  - Glob
---

Directory Structure

.claude/skills/skill-name/
  SKILL.md           # Required
  supporting.md      # Optional, one level only

Tool Permission Matrix

| Task Type | Required Tools | |-----------|----------------| | Read/analyze | Read, Glob | | Search content | Read, Glob, Grep | | Write docs | Read, Write, Glob | | Edit files | Read, Edit, Glob | | Run commands | Bash, Read |

Supporting Files

templates/skill-template.md - Comprehensive skill template
cookbook/validation.md - Validation checklist and scripts
cookbook/patterns.md - Common skill patterns with examples
cookbook/anti-patterns.md - What NOT to do

Agent Skills: Skill Writer

Install this agent skill to your local

Skill Files