technical-documentation-authoring
npx machina-cli add skill paleo/alignfirst/technical-documentation-authoring --openclawTechnical 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'
descriptionfields 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
Source
git clone https://github.com/paleo/alignfirst/blob/main/skills/technical-documentation-authoring/SKILL.mdView on GitHub Overview
Technical Documentation Authoring helps you create or augment skill documentation and project docs such as AGENTS.md. It defines when to bootstrap analysis, how to structure SKILL.md, and how to apply frontmatter and writing guidelines. This ensures clear, consistent docs for agent skills and project references.
How This Skill Works
Analyzes user intent to decide between creating a new skill or updating existing content. It guides placement between SKILL.md and references/, then outputs concise content that follows the project’s frontmatter format and writing guidelines.
When to Use It
- You are creating a new skill and need a formal SKILL.md
- You are updating the description, usage, or parameters of an existing skill
- You are modifying project-wide documentation like AGENTS.md
- You want to bootstrap skills by analyzing the codebase (optional)
- You need to add or refine references content such as bootstrapping-skills.md
Quick Start
- Step 1: Clarify the documentation scope and target audience with the user
- Step 2: Determine placement: SKILL.md for skill-level docs, references/ for deeper guidance
- Step 3: Write SKILL.md with frontmatter (name, description) and concise content, following the 40–80 lines guideline for new docs
Best Practices
- Keep SKILL.md under 500 lines
- Target an experienced newcomer with concise, specific content
- Use a clear title and a specific purpose for each document
- Follow the lowercase-hyphen naming convention for skill dirs
- Include frontmatter with name and description and place content in SKILL.md (or references when appropriate)
Example Use Cases
- Create a new SKILL.md for a technical-documentation-authoring skill
- Update a skill description to reflect bootstrapping and codebase analysis
- Modify AGENTS.md to document new documentation workflow
- Add references/bootstrapping-skills.md to explain codebase bootstrapping
- Align project docs with the Agent Skills specification
