AgentAlley
Submit

Template: How-To Guide skill

Template Name: How-To Guide (Step-by-Step Tutorial)

by AgriciDaniel·MIT license·★ 2,219 Stars on the repo·GitHub ↗

Use now

Files of Template: How-To Guide

AgriciDaniel/main1 file
how-to-guide.md
Show the full text255 lines
template-how-to-guide/how-to-guide.md255 lines · 9.7 KB
Outline
RawView on GitHub

Template: How-To Guide

Template Name: How-To Guide (Step-by-Step Tutorial) Target Word Count: 2,000-2,500 words Description: A structured, actionable tutorial that walks readers through a specific process from start to finish. Each step is concrete, visual, and builds on the previous one. Designed to rank for "how to" queries and earn featured snippets.

When to Use This Template

  • Content Goals: Drive organic traffic from instructional queries, establish topical authority, earn featured snippets for step-based queries
  • Search Intent: Informational / Transactional hybrid: the reader has a specific problem and wants a clear solution right now
  • Best For: Process explanations, software tutorials, setup guides, configuration walkthroughs, skill-building content
  • Avoid When: The topic lacks a clear sequential process or has fewer than 3 meaningful steps

Section-by-Section Structure

Title (H1)

Format: "How to [Achieve X]: A [Year] Step-by-Step Guide"

Examples:

  • "How to Set Up a CI/CD Pipeline: A 2026 Step-by-Step Guide"
  • "How to Migrate from WordPress to Next.js: A 2026 Step-by-Step Guide"

Rules:

  • Include the primary keyword naturally
  • Include the year for freshness signals
  • Keep under 60 characters if possible
Introduction (150-200 words)

[ANSWER-FIRST] Open with the single most compelling statistic or fact that validates why this process matters. Not a vague claim: a specific number.

Structure:

  1. Problem statement (1-2 sentences): What pain point does the reader have?
  2. Agitation (1-2 sentences): What happens if they don't solve it? What's the cost of inaction?
  3. Promise (1 sentence): What will they be able to do after following this guide?
  4. Credibility anchor (1 sentence): Why should they trust this guide specifically?

[STAT: Industry statistic that quantifies the problem this guide solves]

[INFO-GAIN: personal experience] Share a specific, brief anecdote about encountering this problem yourself: when, what happened, what the stakes were.

Example opening:

"[STAT: 73% of deployments fail due to misconfigured pipelines (Source, Year).] If you've ever pushed code on a Friday and spent the weekend firefighting, you already know the pain. This guide walks you through setting up a bulletproof CI/CD pipeline in under an hour: the same process we used to reduce deployment failures by 90% across 12 projects."

[INTERNAL-LINK] Link to a related foundational concept post (e.g., "If you're new to [topic], start with our [Beginner's Guide to X]").

Prerequisites / Before You Begin (100-150 words)

Format: Bulleted checklist under an H2 heading.

Include:

  • Required tools/software (with versions)
  • Required accounts or access
  • Assumed knowledge level (be specific: "You should be comfortable with [X]")
  • Estimated time to complete
  • Difficulty level (Beginner / Intermediate / Advanced)

[IMAGE] Screenshot or diagram showing the tools/environment the reader should have ready before starting.

Example:

What you'll need:

  • Current active LTS version of Node.js installed (how to install)
  • A GitHub account with repo access
  • Basic familiarity with the terminal
  • Time: ~45 minutes
  • Difficulty: Intermediate
Step 1: [Action Verb] + [Specific Object] (200-300 words)

[ANSWER-FIRST] Open with what the reader will have accomplished by the end of this step: the micro-outcome.

Structure for EVERY step section:

  1. Micro-outcome statement (1 sentence): "By the end of this step, you'll have [specific result]."
  2. Context (1-2 sentences): Why this step matters in the overall process.
  3. Instructions (numbered sub-steps): Concrete actions. Use code blocks, exact UI paths, or specific settings.
  4. Verification (1-2 sentences): How the reader confirms this step worked.

[IMAGE] Screenshot showing the expected state after completing this step.

[INFO-GAIN: specific configuration or setting] Share a non-obvious detail: a specific config value, flag, or option that makes a difference and isn't in the official docs.

Formatting rules:

  • Use H2 for the step heading: ## Step 1: Install and Configure the CLI
  • Use numbered sub-lists for individual actions within the step
  • Use code blocks for any commands, file contents, or configuration
  • Bold the single most important instruction in each step
Step 2: [Action Verb] + [Specific Object] (200-300 words)

[Follow the same structure as Step 1]

[IMAGE] Screenshot of expected state after this step.

[STAT: Performance or efficiency metric related to this step, if applicable]

Step 3: [Action Verb] + [Specific Object] (200-300 words)

[Follow the same structure as Step 1]

[IMAGE] Screenshot of expected state after this step.

[VISUAL: flowchart] If the process branches or has decision points at this stage, include a flowchart showing the paths.

Step 4: [Action Verb] + [Specific Object] (200-300 words)

[Follow the same structure as Step 1]

[IMAGE] Screenshot of expected state after this step.

[INFO-GAIN: troubleshooting tip] Share a problem you personally encountered at this stage and how you solved it.

Step 5: [Action Verb] + [Specific Object] (200-300 words)

[Follow the same structure as Step 1]

[IMAGE] Screenshot of expected state after this step.

Step 6: [Action Verb] + [Specific Object] (200-300 words)

[Follow the same structure as Step 1]

[IMAGE] Screenshot showing the final completed state.

[VISUAL: before-after] Side-by-side comparison showing before (Step 1) and after (Step 6) state.

Note: Not every guide needs exactly 6 steps. Use 4-8 steps depending on the complexity of the process. Each step should represent a meaningful, testable milestone: not a trivial action.

Common Mistakes to Avoid (150-200 words)

[ANSWER-FIRST] Open with the single most frequent mistake and its consequence: "[X]% of people get stuck on [Y] because they [Z]."

Format: 3-5 mistakes, each as a bolded sub-heading with 2-3 sentences of explanation.

Structure for each mistake:

  1. The mistake (bold): What people do wrong
  2. Why it happens (1 sentence): The underlying cause or misconception
  3. The fix (1 sentence): What to do instead

[INFO-GAIN: original observation] Include at least one mistake that comes from your direct experience: something not commonly listed in other guides.

[STAT: Failure rate or error frequency for the most common mistake]

Example:

1. Skipping environment variable validation Most tutorials assume your .env file is correctly formatted, but in our experience, 40% of "it works on my machine" bugs trace back to missing or malformed env vars. Always run printenv | grep APP_ before deploying.

Results / What Success Looks Like (100-150 words)

[ANSWER-FIRST] Open with the specific, measurable outcome: "If everything went correctly, you should now see [X]."

Include:

  • What the reader should see/have now (concrete, verifiable)
  • Key metrics that indicate success (load time, response code, test pass rate, etc.)
  • One "stretch goal" or next-level enhancement they can pursue

[IMAGE] Screenshot of the final successful result.

[VISUAL: metrics-dashboard] If applicable, show a performance or status dashboard screenshot.

[INTERNAL-LINK] Link to an advanced guide or next-step post: "Now that you've set up [X], learn how to [optimize/scale/extend it]."

Frequently Asked Questions (5 questions)

[FAQ]

Format: Each question as an H3, answer in 2-4 sentences. Structure answers for featured snippet eligibility.

Question selection criteria:

  1. The most common "People Also Ask" question for this topic
  2. A question about an alternative approach ("Can I do this with [Y] instead?")
  3. A question about troubleshooting ("What if [X] doesn't work?")
  4. A question about scaling or advanced use ("How do I [extend this]?")
  5. A question about cost, time, or prerequisites ("How long does this take?" / "Is [X] free?")

[STAT: Include at least one statistic in your FAQ answers]

Example:

How long does it take to set up a CI/CD pipeline?

[2-4 sentence answer with a specific time range and what variables affect it.]

Can I use [Alternative Tool] instead?

[2-4 sentence answer comparing the alternative, with a clear recommendation.]

What should I do if Step [N] fails?

[2-4 sentence answer with specific troubleshooting steps.]

How do I scale this for a larger team?

[2-4 sentence answer with concrete next steps.]

Is [Tool/Service] free?

[2-4 sentence answer with pricing details and free tier limitations.]

Conclusion with CTA (50-100 words)

Structure:

  1. Recap (1 sentence): Summarize what they accomplished.
  2. Reinforce value (1 sentence): Restate the benefit with the key metric.
  3. CTA (1-2 sentences): Clear next action: share the post, subscribe, try a related guide, leave a comment with their results.

[INTERNAL-LINK] Link to 2-3 related posts for continued reading.

Template Checklist

Before publishing, verify:

  • Title includes primary keyword and current year
  • Introduction opens with a specific statistic, not a generic claim
  • Every step has a clear micro-outcome, numbered sub-steps, and verification
  • Every step has a supporting screenshot or visual
  • At least 2 [INFO-GAIN] elements with original experience or data
  • At least 3 [STAT] markers filled with sourced statistics
  • Common mistakes section includes at least one original observation
  • FAQ answers are structured for featured snippet eligibility
  • All [INTERNAL-LINK] zones have contextual links to related content
  • Word count falls within 2,000-2,500 range
  • All code blocks are syntax-highlighted and tested
  • Meta description written (under 160 characters, includes primary keyword)
1# Template: How-To Guide
2 
3**Template Name:** How-To Guide (Step-by-Step Tutorial)
4**Target Word Count:** 2,000-2,500 words
5**Description:** A structured, actionable tutorial that walks readers through a specific process from start to finish. Each step is concrete, visual, and builds on the previous one. Designed to rank for "how to" queries and earn featured snippets.
6 
7## When to Use This Template
8 
9- **Content Goals:** Drive organic traffic from instructional queries, establish topical authority, earn featured snippets for step-based queries
10- **Search Intent:** Informational / Transactional hybrid: the reader has a specific problem and wants a clear solution *right now*
11- **Best For:** Process explanations, software tutorials, setup guides, configuration walkthroughs, skill-building content
12- **Avoid When:** The topic lacks a clear sequential process or has fewer than 3 meaningful steps
13 
14---
15 
16## Section-by-Section Structure
17 
18---
19 
20### Title (H1)
21 
22**Format:** "How to [Achieve X]: A [Year] Step-by-Step Guide"
23 
24**Examples:**
25- "How to Set Up a CI/CD Pipeline: A 2026 Step-by-Step Guide"
26- "How to Migrate from WordPress to Next.js: A 2026 Step-by-Step Guide"
27 
28**Rules:**
29- Include the primary keyword naturally
30- Include the year for freshness signals
31- Keep under 60 characters if possible
32 
33---
34 
35### Introduction (150-200 words)
36 
37[ANSWER-FIRST] Open with the single most compelling statistic or fact that validates *why* this process matters. Not a vague claim: a specific number.
38 
39**Structure:**
401. **Problem statement** (1-2 sentences): What pain point does the reader have?
412. **Agitation** (1-2 sentences): What happens if they don't solve it? What's the cost of inaction?
423. **Promise** (1 sentence): What will they be able to do after following this guide?
434. **Credibility anchor** (1 sentence): Why should they trust this guide specifically?
44 
45[STAT: Industry statistic that quantifies the problem this guide solves]
46 
47[INFO-GAIN: personal experience] Share a specific, brief anecdote about encountering this problem yourself: when, what happened, what the stakes were.
48 
49**Example opening:**
50> "[STAT: 73% of deployments fail due to misconfigured pipelines (Source, Year).] If you've ever pushed code on a Friday and spent the weekend firefighting, you already know the pain. This guide walks you through setting up a bulletproof CI/CD pipeline in under an hour: the same process we used to reduce deployment failures by 90% across 12 projects."
51 
52[INTERNAL-LINK] Link to a related foundational concept post (e.g., "If you're new to [topic], start with our [Beginner's Guide to X]").
53 
54---
55 
56### Prerequisites / Before You Begin (100-150 words)
57 
58**Format:** Bulleted checklist under an H2 heading.
59 
60**Include:**
61- Required tools/software (with versions)
62- Required accounts or access
63- Assumed knowledge level (be specific: "You should be comfortable with [X]")
64- Estimated time to complete
65- Difficulty level (Beginner / Intermediate / Advanced)
66 
67[IMAGE] Screenshot or diagram showing the tools/environment the reader should have ready before starting.
68 
69**Example:**
70> **What you'll need:**
71> - Current active LTS version of Node.js installed ([how to install](/link))
72> - A GitHub account with repo access
73> - Basic familiarity with the terminal
74> - **Time:** ~45 minutes
75> - **Difficulty:** Intermediate
76 
77---
78 
79### Step 1: [Action Verb] + [Specific Object] (200-300 words)
80 
81[ANSWER-FIRST] Open with what the reader will have accomplished by the end of this step: the micro-outcome.
82 
83**Structure for EVERY step section:**
841. **Micro-outcome statement** (1 sentence): "By the end of this step, you'll have [specific result]."
852. **Context** (1-2 sentences): Why this step matters in the overall process.
863. **Instructions** (numbered sub-steps): Concrete actions. Use code blocks, exact UI paths, or specific settings.
874. **Verification** (1-2 sentences): How the reader confirms this step worked.
88 
89[IMAGE] Screenshot showing the expected state after completing this step.
90 
91[INFO-GAIN: specific configuration or setting] Share a non-obvious detail: a specific config value, flag, or option that makes a difference and isn't in the official docs.
92 
93**Formatting rules:**
94- Use H2 for the step heading: `## Step 1: Install and Configure the CLI`
95- Use numbered sub-lists for individual actions within the step
96- Use code blocks for any commands, file contents, or configuration
97- Bold the single most important instruction in each step
98 
99---
100 
101### Step 2: [Action Verb] + [Specific Object] (200-300 words)
102 
103[Follow the same structure as Step 1]
104 
105[IMAGE] Screenshot of expected state after this step.
106 
107[STAT: Performance or efficiency metric related to this step, if applicable]
108 
109---
110 
111### Step 3: [Action Verb] + [Specific Object] (200-300 words)
112 
113[Follow the same structure as Step 1]
114 
115[IMAGE] Screenshot of expected state after this step.
116 
117[VISUAL: flowchart] If the process branches or has decision points at this stage, include a flowchart showing the paths.
118 
119---
120 
121### Step 4: [Action Verb] + [Specific Object] (200-300 words)
122 
123[Follow the same structure as Step 1]
124 
125[IMAGE] Screenshot of expected state after this step.
126 
127[INFO-GAIN: troubleshooting tip] Share a problem you personally encountered at this stage and how you solved it.
128 
129---
130 
131### Step 5: [Action Verb] + [Specific Object] (200-300 words)
132 
133[Follow the same structure as Step 1]
134 
135[IMAGE] Screenshot of expected state after this step.
136 
137---
138 
139### Step 6: [Action Verb] + [Specific Object] (200-300 words)
140 
141[Follow the same structure as Step 1]
142 
143[IMAGE] Screenshot showing the final completed state.
144 
145[VISUAL: before-after] Side-by-side comparison showing before (Step 1) and after (Step 6) state.
146 
147**Note:** Not every guide needs exactly 6 steps. Use 4-8 steps depending on the complexity of the process. Each step should represent a meaningful, testable milestone: not a trivial action.
148 
149---
150 
151### Common Mistakes to Avoid (150-200 words)
152 
153[ANSWER-FIRST] Open with the single most frequent mistake and its consequence: "[X]% of people get stuck on [Y] because they [Z]."
154 
155**Format:** 3-5 mistakes, each as a bolded sub-heading with 2-3 sentences of explanation.
156 
157**Structure for each mistake:**
1581. **The mistake** (bold): What people do wrong
1592. **Why it happens** (1 sentence): The underlying cause or misconception
1603. **The fix** (1 sentence): What to do instead
161 
162[INFO-GAIN: original observation] Include at least one mistake that comes from your direct experience: something not commonly listed in other guides.
163 
164[STAT: Failure rate or error frequency for the most common mistake]
165 
166**Example:**
167> **1. Skipping environment variable validation**
168> Most tutorials assume your `.env` file is correctly formatted, but in our experience, 40% of "it works on my machine" bugs trace back to missing or malformed env vars. Always run `printenv | grep APP_` before deploying.
169 
170---
171 
172### Results / What Success Looks Like (100-150 words)
173 
174[ANSWER-FIRST] Open with the specific, measurable outcome: "If everything went correctly, you should now see [X]."
175 
176**Include:**
177- What the reader should see/have now (concrete, verifiable)
178- Key metrics that indicate success (load time, response code, test pass rate, etc.)
179- One "stretch goal" or next-level enhancement they can pursue
180 
181[IMAGE] Screenshot of the final successful result.
182 
183[VISUAL: metrics-dashboard] If applicable, show a performance or status dashboard screenshot.
184 
185[INTERNAL-LINK] Link to an advanced guide or next-step post: "Now that you've set up [X], learn how to [optimize/scale/extend it]."
186 
187---
188 
189### Frequently Asked Questions (5 questions)
190 
191[FAQ]
192 
193**Format:** Each question as an H3, answer in 2-4 sentences. Structure answers for featured snippet eligibility.
194 
195**Question selection criteria:**
1961. The most common "People Also Ask" question for this topic
1972. A question about an alternative approach ("Can I do this with [Y] instead?")
1983. A question about troubleshooting ("What if [X] doesn't work?")
1994. A question about scaling or advanced use ("How do I [extend this]?")
2005. A question about cost, time, or prerequisites ("How long does this take?" / "Is [X] free?")
201 
202[STAT: Include at least one statistic in your FAQ answers]
203 
204**Example:**
205 
206#### How long does it take to set up a CI/CD pipeline?
207 
208[2-4 sentence answer with a specific time range and what variables affect it.]
209 
210#### Can I use [Alternative Tool] instead?
211 
212[2-4 sentence answer comparing the alternative, with a clear recommendation.]
213 
214#### What should I do if Step [N] fails?
215 
216[2-4 sentence answer with specific troubleshooting steps.]
217 
218#### How do I scale this for a larger team?
219 
220[2-4 sentence answer with concrete next steps.]
221 
222#### Is [Tool/Service] free?
223 
224[2-4 sentence answer with pricing details and free tier limitations.]
225 
226---
227 
228### Conclusion with CTA (50-100 words)
229 
230**Structure:**
2311. **Recap** (1 sentence): Summarize what they accomplished.
2322. **Reinforce value** (1 sentence): Restate the benefit with the key metric.
2333. **CTA** (1-2 sentences): Clear next action: share the post, subscribe, try a related guide, leave a comment with their results.
234 
235[INTERNAL-LINK] Link to 2-3 related posts for continued reading.
236 
237---
238 
239## Template Checklist
240 
241Before publishing, verify:
242 
243- [ ] Title includes primary keyword and current year
244- [ ] Introduction opens with a specific statistic, not a generic claim
245- [ ] Every step has a clear micro-outcome, numbered sub-steps, and verification
246- [ ] Every step has a supporting screenshot or visual
247- [ ] At least 2 [INFO-GAIN] elements with original experience or data
248- [ ] At least 3 [STAT] markers filled with sourced statistics
249- [ ] Common mistakes section includes at least one original observation
250- [ ] FAQ answers are structured for featured snippet eligibility
251- [ ] All [INTERNAL-LINK] zones have contextual links to related content
252- [ ] Word count falls within 2,000-2,500 range
253- [ ] All code blocks are syntax-highlighted and tested
254- [ ] Meta description written (under 160 characters, includes primary keyword)
255 

Discussion

Browse more free Claude skills.