Skip to main content

Capability Guide Template

Capability guides turn human potential into trainable agency.

Use this template for /docs/agency/capabilities/** pages and any page whose job is to improve a capability a person or team can practice.

Instructions​

Page type: concept. Diataxis class: explanation with embedded playbook. Writing layer: Hemingway, always.

Primary reader: a human improving agency. Secondary reader: an AI agent classifying, routing, checking, or improving the page.

Rules:

  1. Open with one provocative sentence. No preamble.
  2. Put a visual immediately after the opener: YouTube iframe or generated image/component.
  3. If no excellent video exists and no generated visual exists, do not publish visual-free.
  4. Route repeated visual needs as a future generated-visual Unit of Work or Module candidate through .FLOW/WORKCHARTS/_MODULES.
  5. Use bullets and short labelled blocks before tables.
  6. Use tables only for compact comparisons that work on mobile.
  7. Every heading is three words or fewer.
  8. Teach the capability as a loop: trigger, response, feedback, practice, proof.
  9. Include ## Agent Use so AI agents know the page job, page type, and improvement target.
  10. End with ## Context and 3-6 links with scent.
  11. Do not leak private project state into reader-facing content.

Page Shape​

Use this order.

---
title: Capability Name
sidebar_label: Capability Name
description: "Direct answer to what this capability helps the reader do."
tags:
  - Capabilities
  - Agency
type: concept
loop_phase: action
level: working
---

Provocative opener.

<div className="iframe-container">
  <iframe
    className="responsive-iframe"
    src="https://www.youtube.com/embed/VIDEO_ID"
    frameBorder="0"
    height="400"
    allowFullScreen
    width="100%"
  ></iframe>
</div>

Core insight in one or two sentences.

## Model

Name the loop.

## Breakdowns

Show how the weak pattern fails.

## Protocol

Give the repeatable method.

## Practice

Give daily or weekly reps.

## Diagnostic

Give observable checks.

## Shadow

Name the failure mode of overuse or misuse.

## Agent Use

Tell AI agents how to classify and improve the page.

## Questions

Ask questions that improve agency.

## Context

- [Related page](/docs/) — why it matters

Content Rules​

Hemingway first. Cut throat-clearing. Use short sentences. Prefer strong verbs. Keep the core sentence visible.

Pattern before detail. The brain learns through repeated shapes. Name the loop before explaining parts.

Practice before summary. A capability page fails if the reader cannot do one thing after reading it.

Mobile first. Use labelled bullets, short lists, and narrow comparisons. Avoid wide tables. If a table needs more than three columns, rewrite it.

AI readable. Use frontmatter, stable headings, direct definitions, and ## Agent Use. Agents should know the page job without inferring it from prose.

Agency focused. The page exists to develop agency: better perception, better action, better feedback, better standards.

Visual Rule​

Every capability guide needs one first-screen visual.

Use one of these:

  • YouTube iframe — when a single excellent video explains the idea better than text.
  • Generated image or component — when the page teaches a loop, contrast, or system.
  • Future Module candidate — when the visual need repeats across pages and should become reusable.

The visual is not decoration. It must make the pattern easier to remember.

Agent Use​

  • Page type: concept
  • Template: capability-guide-template
  • Primary job: improve a trainable agency capability
  • Required media: YouTube iframe or generated visual
  • Writing layer: Hemingway
  • Mobile rule: avoid wide tables
  • AI target: frontmatter, stable headings, and direct practice protocol

Questions​

  • What is the one loop this capability trains?
  • What does weak practice look like?
  • What does strong practice look like?
  • What proof would show the capability improved?

Context​