How do I install the Writing How To Guides skill?

Run npx skillmds@latest add tomevault-io/writing-how-to-guides in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Writing How To Guides safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Writing How To Guides?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Writing How To Guides free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Writing How To Guides?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Writing How To Guides by tomevault-io

Name: Writing How To Guides
Author: tomevault-io

Writing How To Guides

Write a Diátaxis how-to guide, ie goal-oriented documentation that directs a competent user through the steps to accomplish a specific real-world task. Use when the reader already knows the basics and needs to get something done, not when teaching a beginner (tutorial) or describing the machinery (reference). Load the `diataxis` skill first if unsure which mode applies. Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Writing how-to guides

A how-to guide is a recipe: directions that take a user through the steps to achieve a specific end. It is goal-oriented and serves users who are working, not studying. It assumes competence. Its job is to answer a real question of the form "How do I do X?".

A good how-to guide is the clearest demonstration of what your product can actually do for someone.

How to write one

Address a real problem, from the user's side. Frame it around what the user wants to achieve ("how to calibrate the radar array", "how to configure reconnection policies"), not around the machinery. Describing tool mechanics for their own sake is mostly useless to someone who already has basic competence.
Keep one goal in focus. A how-to guide is about a task with a practical goal. Maintain focus on that goal. Do not wander into teaching or explanation.
Provide an executable sequence. Lay out the steps as a logical contract: given situation X, do these things, and you will reach result Y. Steps include judgment and decisions, not just mechanical commands.
Sequence with real-world logic. Order the steps the way the work actually flows. Anticipate what the user needs next and present it exactly when needed, so the guide seems to read the user's mind. This is flow.
Stay adaptable. Real users have varying situations. Address the task in a way they can adapt, rather than a single brittle path. Use conditional imperatives: "If you want x, do y."
Be usefully incomplete. Prefer practical usability over completeness. Start and stop at sensible points; the user slots the guide into their own work. Omit anything not needed to reach the goal.

Naming

Name it by exactly what it lets the user do. The title should answer "how to...".

Good: "How to integrate application performance monitoring"
Ambiguous: "Integrating application performance monitoring" (do, or decide?)
Useless: "Application performance monitoring" (a topic, not a task)

Scope must be specific and bounded. "How to build a web application" is too broad to be a how-to guide; it has no defined endpoint.

Language patterns

Open with "This guide shows you how to...".
Use conditional imperatives: "If you want x, do y".
Point elsewhere for detail: "Refer to the x reference for the full options" rather than reproducing reference material inline.

What to avoid

Including explanation or teaching material.
Defining the guide around tool functions instead of user problems.
Reaching for reference-level completeness when focus matters more.
Titles that hide the guide's real scope or intent.

Source: mrchantey/beet — distributed by TomeVault.

---name: writing-how-to-guidesdescription: Write a Diátaxis how-to guide, ie goal-oriented documentation that directs a competent user through the steps to accomplish a specific real-world task. Use when the reader already knows the basics and needs to get something done, not when teaching a beginner (tutorial) or describing the machinery (reference). Load the `diataxis` skill first if unsure which mode applies. Use when this capability is needed.---# Writing how-to guidesA how-to guide is a recipe: directions that take a user through the steps to achievea specific end. It is **goal-oriented** and serves users who are *working*, notstudying. It assumes competence. Its job is to answer a real question of the form"How do I do X?".A good how-to guide is the clearest demonstration of what your product can actuallydo for someone.## How to write one1. **Address a real problem, from the user's side.** Frame it around what the user wants to achieve ("how to calibrate the radar array", "how to configure reconnection policies"), not around the machinery. Describing tool mechanics for their own sake is mostly useless to someone who already has basic competence.2. **Keep one goal in focus.** A how-to guide is about a task with a practical goal. Maintain focus on that goal. Do not wander into teaching or explanation.3. **Provide an executable sequence.** Lay out the steps as a logical contract: given situation X, do these things, and you will reach result Y. Steps include judgment and decisions, not just mechanical commands.4. **Sequence with real-world logic.** Order the steps the way the work actually flows. Anticipate what the user needs next and present it exactly when needed, so the guide seems to read the user's mind. This is *flow*.5. **Stay adaptable.** Real users have varying situations. Address the task in a way they can adapt, rather than a single brittle path. Use conditional imperatives: "If you want x, do y."6. **Be usefully incomplete.** Prefer practical usability over completeness. Start and stop at sensible points; the user slots the guide into their own work. Omit anything not needed to reach the goal.## NamingName it by exactly what it lets the user do. The title should answer "how to...".- Good: "How to integrate application performance monitoring"- Ambiguous: "Integrating application performance monitoring" (do, or decide?)- Useless: "Application performance monitoring" (a topic, not a task)Scope must be specific and bounded. "How to build a web application" is too broad tobe a how-to guide; it has no defined endpoint.## Language patterns- Open with "This guide shows you how to...".- Use conditional imperatives: "If you want x, do y".- Point elsewhere for detail: "Refer to the x reference for the full options" rather than reproducing reference material inline.## What to avoid- Including explanation or teaching material.- Defining the guide around tool functions instead of user problems.- Reaching for reference-level completeness when focus matters more.- Titles that hide the guide's real scope or intent.---> Source: [mrchantey/beet](https://github.com/mrchantey/beet) — distributed by [TomeVault](https://tomevault.io).

Frequently asked questions