Agent-Skills.md

Agent Skills: 5-Style Documentation System

Generate standardized project documentation using the 5-style system. Use when asked to create plans, specs, skills, RFCs, ADRs, or other project documentation. Ensures consistent, high-quality documentation across the codebase.

UncategorizedID: thrashr888/thrashr888-agent-kit/style-docs
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/thrashr888/thrashr888-agent-kit/tree/HEAD/skills/style-docs

Skill Files

Browse the full folder contents for style-docs.

Download Skill

Loading file tree…

skills/style-docs/SKILL.md

Skill Metadata

Name
style-docs
Description
Generate standardized project documentation using the 5-style system. Use when asked to create plans, specs, skills, RFCs, ADRs, or other project documentation. Ensures consistent, high-quality documentation across the codebase.

5-Style Documentation System

Use this skill when creating project documentation, planning features, or organizing technical decisions.

Agent-Ready Documentation

Document intent, constraints, and rationale that code alone cannot reveal. Agents can inspect implementation details, but they cannot infer requirements discussed in meetings, external contracts, business rules, or the reason a non-obvious decision was made. Put those facts in the narrowest durable artifact:

  • requirements and plans define observable acceptance criteria and non-goals;
  • specs record invariants, external constraints, and architectural boundaries;
  • ADRs record a significant decision and its rationale; and
  • skills record a repeatable implementation or verification workflow.

Do not write documentation that merely paraphrases code. Before publishing a document, ask whether a future engineer or agent could learn why this behavior exists and how to prove it still meets its constraints.

The 5 Documentation Styles

| Style | Purpose | Location | Update Trigger | | ------------------ | --------------------------------- | ----------------- | -------------------- | | 1. Plan Mode | Deep exploration before coding | plans/ | Per feature | | 2. Issues | Track work across sessions | .beads/ or GH | Throughout feature | | 3. Evergreen Specs | System truth ("how it works") | specs/ | Architecture changes | | 4. Skills | Agent guides ("how to implement") | .claude/skills/ | Pattern changes | | 5. User Docs | Human communication | README, CLAUDE.md | Major features |

When to Use Each Style

Style 1: Plan Mode (plans/)

Purpose: Explore and design before coding

When to use:

  • Starting a non-trivial feature
  • Making architectural decisions
  • Complex refactoring

File naming: plans/YYYY-MM-DD-feature-name.md

Template: See references/plan-template.md

Style 2: Issues (.beads/ or GitHub)

Purpose: Track work items and dependencies

When to use:

  • Work spans multiple sessions
  • Feature has dependencies
  • Need to track blockers

Commands:

bd create --title="..." --type=task|bug|feature --priority=2
bd update <id> --status=in_progress
bd close <id>

Style 3: Specs (specs/)

Purpose: Document architectural truth - WHAT the system does

When to use:

  • Architecture changes
  • New subsystems added
  • Core patterns established

Characteristics:

  • Declarative, not prescriptive
  • Evergreen (rarely becomes stale)
  • Describes intent, constraints, and invariants
  • States the rationale behind non-obvious boundaries

Template: See references/spec-template.md

Style 4: Skills (.claude/skills/)

Purpose: Guide agents on HOW to implement

When to use:

  • New implementation patterns
  • Workflow documentation
  • Agent guidance needed

Characteristics:

  • Prescriptive (step-by-step)
  • Code examples
  • Tool allowlists

Template: See references/skill-template.md

Style 5: User Docs (README, CLAUDE.md)

Purpose: Human-facing communication

When to use:

  • Public-facing changes
  • Getting started guides
  • API documentation

Files:

  • README.md: Project overview, installation
  • CLAUDE.md: Agent instructions
  • AGENTS.md: Compiled agent instructions

Decision Framework

| Situation | Action | | -------------------------- | --------------------------------- | | Starting new feature | Enter plan mode → write to plans/ | | Feature spans sessions | Create beads issue | | New architectural pattern | Update spec in specs/ | | New implementation pattern | Update skill in .claude/skills/ | | Public-facing change | Update README.md | | Agent guidance needed | Update CLAUDE.md |

Additional Templates

For specific use cases:

  • RFC (references/rfc-template.md): Formal proposals needing team input
  • ADR (references/adr-template.md): Architecture decision records
  • Bug Report (references/bug-report-template.md): Bug documentation
  • Feature Request (references/feature-request-template.md): Feature proposals
  • Pull Request (references/pull-request-template.md): PR descriptions

Anti-Patterns

DON'T:

  • Write RFC-style docs that get stale ("We plan to add X")
  • Document temporary decisions in specs (use issues)
  • Put implementation details in specs (use skills)
  • Put architectural constraints in skills (use specs)

DO:

  • Keep specs declarative and evergreen
  • Keep skills prescriptive and code-focused
  • Track multi-session work in issues
  • Update docs when patterns change

Resources

All templates available in references/:

  • plan-template.md - Plan mode template
  • spec-template.md - Evergreen spec template
  • skill-template.md - Skill document template
  • rfc-template.md - RFC template
  • adr-template.md - ADR template
  • bug-report-template.md - Bug report template
  • feature-request-template.md - Feature request template
  • pull-request-template.md - PR description template