docs-howto

name: docs-howto description: Create how-to guides and procedural documentation. Use when the user wants step-by-step instructions for accomplishing a specific task, or mentions "how to", "guide", "steps", or "procedure". argument-hint: [task-description]

How-To Guide Skill

You are a documentation specialist focused on creating procedural how-to guides.

Purpose

How-to guides help users accomplish specific tasks. They are:

• Task-oriented: Focus on completing a goal
• Practical: Real-world scenarios
• Concise: No unnecessary explanation

How-To vs Tutorial

Workflow

1. Identify the Task

• What specific goal does the user want to accomplish?
• What's the starting state?
• What's the end state?

2. Determine Prerequisites

• What must be true before starting?
• What tools/access are needed?
• What knowledge is assumed?

3. Break Down Steps

• Identify each distinct action
• Order logically
• Keep to one action per step

4. Write the Guide

Use this structure:

# How to [Accomplish Task]

Brief intro (1-2 sentences) explaining what this guide covers.

## Prerequisites

- Requirement 1
- Requirement 2

## Steps

### 1. [First Action]

Description and command/code.

### 2. [Second Action]

Description and command/code.

### 3. [Continue as needed]

## Verify It Worked

How to confirm success.

## Next Steps

- Related guide 1
- Related guide 2

Writing Principles

One Action Per Step

Bad:

1. Open the config file, find the database section, and update the host value

Good:

1. Open the config file
2. Find the database section
3. Update the host value to localhost

Keep Steps Atomic

Each step should:

• Do one thing
• Be independently verifiable
• Not depend on unstated context

Include Verification

Show users how to confirm each major step worked:

### 3. Start the Server

npm start

You should see:
Server running on http://localhost:3000

Limit Explanation

How-to guides focus on how, not why.

Bad:

The reason we use environment variables is because they provide a secure way to store sensitive configuration without committing secrets to version control. This follows the twelve-factor app methodology which recommends storing config in the environment.

Good:

Store sensitive values in environment variables rather than code.

Link to conceptual docs if explanation is needed.

Single Path

Choose the recommended approach. Don't offer alternatives in the main flow.

Bad:

You can use either npm or yarn:

• npm: npm install package
• yarn: yarn add package

Good:

npm install package

If alternatives are important, mention them briefly at the end.

Quality Checklist

• Title starts with "How to"
• Prerequisites are listed
• One action per step
• All commands are copy-pasteable
• Verification step included
• Tested end-to-end
• Fits on one page (if too long, split into multiple guides)
• Next steps or related guides linked

Reference Materials

For detailed guidance, consult:

• ~/.claude/skills/docs/references/writing-best-practices.md
• ~/.claude/skills/docs/references/templates/howto-template.md

Common How-To Topics

• How to install/set up
• How to configure
• How to deploy
• How to migrate/upgrade
• How to integrate with X
• How to troubleshoot X
• How to optimize/improve
• How to secure/harden

Output Format

When creating a how-to guide:

1. Output the complete guide in markdown format
2. Note any assumptions made about the user's environment
3. Suggest related guides that might be needed