documentation-authoring

name	documentation-authoring
description	Create or augment skills and documentation. Use when writing new skills, updating existing skills, or modifying project documentation like AGENTS.md.
license	CC0 1.0
metadata	{"author":"Paleo","version":"1.0","repository":"https://github.com/paleo/vibe-flow"}

Documentation Authoring

References

• Agent Skills specification
• Bootstrapping Skills — infer project-specific skills from codebase analysis

Workflow

0. Bootstrapping (Optional)

If the user asks to bootstrap skills by analyzing the codebase (rather than requesting a specific skill), then read Bootstrapping Skills first. This applies even if reusable skills already exist; the goal is to create project-specific documentation.

1. Understand the Subject

Clarify what needs to be documented. Ask the user if unclear.

2. Determine the Target

For agent skill documentation:

1. Scan existing skills' description fields for keyword matches
2. If a potential match exists, read that skill's content to confirm suitability
3. Decision:
   • User requested a specific skill AND it's suitable → proceed
   • User requested a new skill AND no suitable skill exists → create it
   • Otherwise → discuss with user before proceeding

For general documentation (AGENTS.md, README, etc.): proceed directly.

3. Determine Placement (Skills Only)

• SKILL.md: Essential content required to use the skill
• references/: Optional detailed content that can be skipped

4. Write the Documentation

Follow the guidelines below.

Creating a New Skill

.claude/skills/skill-name/
└── SKILL.md           # Required

Frontmatter:

---
name: skill-name
description: What this skill does and when to use it.
---

The name must match the directory name. Use lowercase with hyphens.

Writing Guidelines

Target audience: An experienced newcomer.

• Be brief and specific
• No obvious information, no generic best practices
• Clear title, specific purpose
• New documents: 40–80 lines typical
• SKILL.md: under 500 lines
• Keep code snippets small; reference source files for full examples