Not all skill files follow the same structure. A tutorial skill differs from a reference skill, which differs from a troubleshooting skill. This skill provides ready-to-use templates for the most common skill archetypes, with guidance on when to use each template and how to customize it for your domain.

## Key Points

- [Tool] version [X]+ installed
- [Environment requirement]
- Basic familiarity with [assumed knowledge]
- [Specific scenario 1]
- [Specific scenario 2]
- [Scenario where different approach needed]
- [Related concept 1] — [How it connects]
- [Related concept 2] — [How it connects]
- [Scenario requiring this understanding]
- [Decision point where this concept matters]
- [Important caveat 1]
- [Important caveat 2]

Skill File Templates and Archetypes

Purpose

Not all skill files follow the same structure. A tutorial skill differs from a reference skill, which differs from a troubleshooting skill. This skill provides ready-to-use templates for the most common skill archetypes, with guidance on when to use each template and how to customize it for your domain.

Skill Archetypes

Archetype Overview

Common Skill Archetypes:
┌────────────────────┬────────────────────────────────────┐
│ Archetype          │ Best For                           │
├────────────────────┼────────────────────────────────────┤
│ How-To             │ Step-by-step procedures            │
│ Concept            │ Explaining models and principles   │
│ Reference          │ Lookup tables, API surfaces, specs │
│ Decision Guide     │ Choosing between approaches        │
│ Troubleshooting    │ Diagnosing and fixing problems     │
│ Pattern Catalog    │ Collection of reusable patterns    │
│ Configuration      │ Setting up tools and environments  │
│ Migration          │ Moving from version A to version B │
└────────────────────┴────────────────────────────────────┘

Template 1: How-To Skill

Best for: Procedures, implementations, "do this thing" tasks.

---
title: "How to [Specific Task] with [Technology]"
category: "category-name"
tags: ["technology", "task", "use-case"]
version: "1.0.0"
---

# How to [Specific Task] with [Technology]

## Purpose

This skill walks through [specific task] using [technology].
By the end, you will have [concrete outcome].
Use this when [scenario where this task is needed].

## Prerequisites

- [Tool] version [X]+ installed
- [Environment requirement]
- Basic familiarity with [assumed knowledge]

## Steps

### Step 1: [Setup/Preparation]

[Explain what this step accomplishes]

```[language]
[command or code]

Verify: [How to confirm this step worked]

Step 2: [Core Action]

[Explain what this step accomplishes]

[command or code]

Verify: [How to confirm this step worked]

Step 3: [Additional Configuration]

[Explain what this step accomplishes]

[command or code]

Step 4: [Final Verification]

[Full end-to-end verification]

[test command or validation]
# Expected output: [what success looks like]

Common Issues

Symptom	Cause	Fix
[Error message]	[Why it happens]	[How to fix]
[Unexpected behavior]	[Why it happens]	[How to fix]

When to Apply This Skill

Use this skill when:

• [Specific scenario 1]
• [Specific scenario 2]

Do not use when:

• [Scenario where different approach needed]

## Template 2: Concept Skill

Best for: Explaining mental models, architecture patterns, design principles.

```markdown
---
title: "[Concept Name] in [Domain]"
category: "category-name"
tags: ["concept", "domain", "principle"]
version: "1.0.0"
---

# [Concept Name] in [Domain]

## Purpose

This skill explains [concept] and how it applies to [domain].
Understanding this concept is essential for [why it matters].
It forms the foundation for [what it enables].

## Core Concept

### What Is [Concept]?

[2-3 sentence plain-language definition]

[Diagram illustrating the concept]

### Why It Matters

[3-5 bullet points on practical impact]

### Key Principles

#### Principle 1: [Name]

[Explanation with example]

#### Principle 2: [Name]

[Explanation with example]

#### Principle 3: [Name]

[Explanation with example]

## Practical Application

### Example: [Real-World Scenario]

[Show the concept applied to a concrete situation]

```[language]
[Code or configuration demonstrating the concept]

Example: [Different Scenario]

[Show the concept in a different context]

Common Misconceptions

Misconception	Reality
"[Wrong belief]"	[Correct understanding]
"[Wrong belief]"	[Correct understanding]

Related Concepts

• [Related concept 1] — [How it connects]
• [Related concept 2] — [How it connects]

When to Apply This Skill

Use this skill when:

• [Scenario requiring this understanding]
• [Decision point where this concept matters]

## Template 3: Reference Skill

Best for: API surfaces, configuration options, syntax references.

```markdown
---
title: "[Technology] [Aspect] Reference"
category: "category-name"
tags: ["reference", "technology", "api"]
version: "1.0.0"
---

# [Technology] [Aspect] Reference

## Purpose

Quick-reference for [aspect] of [technology]. Use this when
you need to look up [specific thing] during implementation.
Not a tutorial — see "[Tutorial Skill Name]" for step-by-step guidance.

## Quick Reference

### [Category 1]

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `option_a` | string | `""` | [What it does] |
| `option_b` | number | `0` | [What it does] |
| `option_c` | boolean | `false` | [What it does] |

### [Category 2]

| Name | Signature | Returns | Description |
|------|-----------|---------|-------------|
| `method_a()` | `(input: Type) => Result` | `Result` | [What it does] |
| `method_b()` | `() => void` | `void` | [What it does] |

## Usage Examples

### [Common Use Case 1]

```[language]
[Minimal example showing the use case]

[Common Use Case 2]

[Minimal example]

Notes

• [Important caveat 1]
• [Important caveat 2]

When to Apply This Skill

Use this skill when:

• Looking up [specific thing] during implementation
• Checking available options for [configuration]

Use the tutorial skill instead when:

• Learning [technology] for the first time
• Setting up from scratch

## Template 4: Decision Guide Skill

Best for: Choosing between technologies, approaches, or architectures.

```markdown
---
title: "Choosing Between [Option A] and [Option B] for [Use Case]"
category: "category-name"
tags: ["decision", "comparison", "architecture"]
version: "1.0.0"
---

# Choosing Between [Option A] and [Option B] for [Use Case]

## Purpose

This skill helps you choose between [Option A] and [Option B]
when building [type of system]. Each has distinct strengths,
and the right choice depends on your specific requirements.

## Quick Decision

Choose [Option A] when: ├── [Condition 1] ├── [Condition 2] └── [Condition 3]

Choose [Option B] when: ├── [Condition 1] ├── [Condition 2] └── [Condition 3]

## Detailed Comparison

| Criterion | [Option A] | [Option B] |
|-----------|-----------|-----------|
| [Criterion 1] | [Rating/details] | [Rating/details] |
| [Criterion 2] | [Rating/details] | [Rating/details] |
| [Criterion 3] | [Rating/details] | [Rating/details] |
| [Criterion 4] | [Rating/details] | [Rating/details] |
| Learning curve | [Assessment] | [Assessment] |
| Community/support | [Assessment] | [Assessment] |

## [Option A] Deep Dive

### Strengths
- [Strength 1 with explanation]
- [Strength 2 with explanation]

### Weaknesses
- [Weakness 1 with explanation]
- [Weakness 2 with explanation]

### Best-Fit Scenarios
[Describe the ideal project for Option A]

## [Option B] Deep Dive

### Strengths
- [Strength 1 with explanation]

### Weaknesses
- [Weakness 1 with explanation]

### Best-Fit Scenarios
[Describe the ideal project for Option B]

## Real-World Decision Examples

### Scenario: [Specific project type]
**Choose: [Option]** because [reasoning]

### Scenario: [Different project type]
**Choose: [Option]** because [reasoning]

## When to Apply This Skill

Use this skill when:
- Starting a new project that requires [capability]
- Evaluating whether to migrate from [Option A] to [Option B]

Template 5: Troubleshooting Skill

Best for: Diagnosing problems, fixing errors, resolving issues.

---
title: "Troubleshooting [Technology] [Problem Area]"
category: "category-name"
tags: ["troubleshooting", "debugging", "errors", "technology"]
version: "1.0.0"
---

# Troubleshooting [Technology] [Problem Area]

## Purpose

This skill helps diagnose and resolve common issues with
[technology] in [context]. Use it when [thing] isn't working
as expected and you need to systematically identify the cause.

## Diagnostic Flowchart

Start: [Problem description] │ ├── Is [basic thing] working? │ ├── No → See "Fix: [Basic Issue]" below │ └── Yes ↓ │ ├── Is [next thing] configured correctly? │ ├── No → See "Fix: [Configuration Issue]" below │ └── Yes ↓ │ ├── Does [operation] produce errors? │ ├── Error: [specific error] → See "Fix: [Error Name]" │ ├── Error: [other error] → See "Fix: [Error Name]" │ └── No errors but wrong result → See "Fix: [Logic Issue]" │ └── Still not working → See "Escalation" section

## Common Issues and Fixes

### Fix: [Issue Name 1]

**Symptom:** [What the user observes]
**Cause:** [Why this happens]
**Fix:**
```[language]
[Commands or code to fix it]

Verify: [How to confirm it's fixed]

Fix: [Issue Name 2]

Symptom: [What the user observes] Cause: [Why this happens] Fix:

[Commands or code to fix it]

Verify: [How to confirm it's fixed]

Fix: [Issue Name 3]

Symptom: [Error message or behavior] Cause: [Root cause explanation] Fix: [Step-by-step resolution]

Diagnostic Commands

Command	What It Shows
[command 1]	[What to look for in output]
[command 2]	[What to look for in output]
[command 3]	[What to look for in output]

Escalation

If none of the above resolves the issue:

1. [Gather this information]
2. [Check this resource]
3. [Contact this support channel]

When to Apply This Skill

Use this skill when:

• [Technology] is producing errors or unexpected behavior
• [Specific operation] is failing
• Performance of [technology] has degraded

## Template 6: Migration Skill

```markdown
---
title: "Migrating from [Old] to [New]"
category: "category-name"
tags: ["migration", "upgrade", "old-technology", "new-technology"]
version: "1.0.0"
---

# Migrating from [Old] to [New]

## Purpose

Step-by-step guide for migrating from [Old version/technology]
to [New version/technology]. Covers breaking changes,
code modifications, testing strategies, and rollback planning.

## Before You Start

### Breaking Changes Summary

| Change | Impact | Migration Path |
|--------|--------|---------------|
| [Change 1] | [What breaks] | [How to fix] |
| [Change 2] | [What breaks] | [How to fix] |

### Prerequisites
- Current codebase on [Old] version [X]
- All tests passing on current version
- [Additional requirements]

### Estimated Effort
- Small project: [time estimate]
- Medium project: [time estimate]
- Large project: [time estimate]

## Migration Steps

### Phase 1: Preparation
[Steps to prepare without breaking current functionality]

### Phase 2: Core Migration
[Steps that change the primary dependency/approach]

### Phase 3: Code Updates
[Steps to update application code for breaking changes]

### Phase 4: Testing
[How to verify the migration succeeded]

### Phase 5: Cleanup
[Remove old dependencies, deprecated code]

## Rollback Plan

If migration fails:
1. [Step to revert]
2. [Step to restore previous state]
3. [How to verify rollback succeeded]

## When to Apply This Skill

Use this skill when:
- Upgrading [technology] from version [X] to [Y]
- Moving from [Old approach] to [New approach]

Choosing a Template

Template Selection Guide:

"I need to explain HOW to do something"
  → How-To template

"I need to explain WHAT something is"
  → Concept template

"I need a quick LOOKUP for options/syntax"
  → Reference template

"I need to help CHOOSE between options"
  → Decision Guide template

"I need to help FIX problems"
  → Troubleshooting template

"I need to help UPGRADE or TRANSITION"
  → Migration template

"I need to show MULTIPLE APPROACHES"
  → Pattern Catalog template (combine multiple How-To patterns)

"My skill doesn't fit any template"
  → Start with How-To (most versatile), adapt as needed

When to Apply This Skill

Use this skill when:

• Starting a new skill file and unsure of structure
• Establishing template standards for a team
• Converting unstructured notes into a proper skill file
• Reviewing a skill that feels disorganized (may need a different archetype)
• Training new skill authors on common structures