---
id: how-to-use-skill-files
name: How to Use ChunkMaps .md Skill Files
version: 1.0.0
tags: [skills, howto, agents, library]
---

# How to use .md skill files

A practical guide for humans and agents working with the ChunkMaps skills library.

## What a skill file is

A **skill file** is a reusable ChunkMaps method pattern written in Markdown. It tells an agent (or a practitioner) **when** to use a pattern, **what inputs** to gather, **which steps** to follow, **what output shape** to produce, and **which guardrails** to enforce.

Skills are not website articles. Articles teach and persuade. Skills are **executable playbooks** you can load into an agent session or follow by hand.

## Where the library lives

| Location | Role |
|---|---|
| `skills/` (repo root) | **Source of truth** - edit here |
| `TEMP/skills/` | **Web preview mirror** - copied on every site rebuild |

Do not edit files under `TEMP/skills/` expecting changes to stick. Always edit repo-root `skills/`, then rebuild TEMP.

## How to open a skill from the TEMP site

1. Open `TEMP/index.html` (or serve `TEMP/` locally).
2. Go to **Articles** (sitemap) or open a mapped article (persuasion / agentic pillars).
3. Use a **Skills library** card or CTA:
   - **How to use .md skill files** (this guide as HTML)
   - **Open skill: ...** links to the mirrored `.md` under `TEMP/skills/`
4. Browse the Skills library page: `chunkmap-skills.html` (raw index still at `skills/README.md`)

Tip: when previewing via `python -m http.server` inside `TEMP/`, paths like `skills/chunkmap-agent-blackboard.md` resolve cleanly.

## How to apply a skill (humans + agents)

Follow this loop every time:

1. **Load the skill** - open the matching `.md` (or paste/attach it into the agent context).
2. **Confirm fit** - check *When to use / audience*. If the job does not match, pick another skill.
3. **Gather inputs** - complete the skill's input table before generating answers.
4. **Follow the procedure** - run the numbered ChunkMaps steps in order; do not skip map/schema steps.
5. **Produce the output schema** - fill the skill's template (outline, YAML, tables, CHUNKS_OK, blackboard, etc.).
6. **Verify guardrails** - run the failure-mode checks; repair anything that invents evidence, drifts domain, or skips citations/IDs.
7. **Hand off** - deliver the structured output to the human, pipeline, or next agent.

### Agent prompt pattern (optional)

```text
Load and follow the ChunkMaps skill: <skill-file-name>.md
Use only the procedure and schemas in that skill.
Gather missing inputs by asking concise questions.
Return the skill's output template, then list guardrail checks you performed.
```

## How to update or add a skill

1. Edit or create `skills/chunkmap-<slug>.md` (keep YAML frontmatter + standard sections).
2. Update the table in `skills/README.md`.
3. If a TEMP article should deep-link to it, set `skill: {file, label, blurb}` on that page in `_build_temp_site.py`.
4. Rebuild: `python _build_temp_site.py` (copies `skills/` to `TEMP/skills/` and regenerates HTML).
5. Bump the skill `version` when behaviour or output schema changes.

## Which skill to pick

| Skill | Pick when you need to... |
|---|---|
| [chunkmap-persuasion-flow.md](./chunkmap-persuasion-flow.md) ([TEMP guide](../chunkmap_persuasion_flow.html)) | Structure human persuasion: Chunk Map, Journey of Persuasion, counterarguments, CHUNKS_OK |
| [chunkmap-agent-blackboard.md](./chunkmap-agent-blackboard.md) | Run multi-agent swarms with a shared state schema and DAG prompt-trees (anti-drift) |
| [chunkmap-policy-to-pipeline.md](./chunkmap-policy-to-pipeline.md) | Compile unstructured policy/SOP prose into versioned, citable logic chunks for AI pipelines |

## Related

- Library index: [README.md](./README.md)
- TEMP HTML guide: `../how_to_use_skill_files.html`
- Articles sitemap: `../chunkmaps_articles.html`