Technical 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:

• Scan existing skills' description fields for keyword matches

• If a potential match exists, read that skill's content to confirm suitability

• 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

{skills-dir}/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