---
name: author-skill-tree
description: Create or edit a Skill Tree's Definition — its Skills, structure, colours, and rubrics — by writing the tree's YAML and validating it against the Engine. Use when the user wants to add, rename, remove, or restructure skills in a Skill Tree, write rubrics, or start a new tree.
---

# Authoring a Skill Tree

A **Skill Tree** is defined by one YAML file — the **Definition**. It describes
the tree's _shape_ only (Skills, structure, colours, rubrics), never a
Practitioner's progress. This Playbook edits that file and proves it is valid.

In this repo the App's Definition is
[`examples/starter-template/content/tree.yaml`](../../examples/starter-template/content/tree.yaml).
Another project points this Playbook at its own Definition file.

## The shape

```yaml
id: my-tree
version: 1
rollup: { defaultStrategy: average } # a parent's Level = average of its children
gating: { defaultStrategy: alwaysUnlocked } # nothing is ever locked
edges: []
nodes:
  - { id: trunk, parentId: null, meta: { title: My Tree, color: '#e8b25a' } }
  - id: writing
    parentId: trunk
    meta:
      title: Writing
      color: '#5ad1c5'
      rubric:
        3: Writes clearly enough that the point survives a second read.
        6: Structures a document so the reader gets the point fast.
        9: Anticipates the reader's question and answers it before it is asked.
```

- Exactly one root: `parentId: null`. Every other node's `parentId` must exist.
- `id`s are unique and kebab-case. `meta.title` and `meta.color` (any CSS colour)
  are required; give each branch its own colour and let its leaves inherit it.

## Rules that keep a tree meaningful

- Every node is a **trainable behaviour**, not a trait.
- Give each **leaf** `3 / 6 / 9` **behavioural anchors** under `rubric:` — what the
  Practitioner actually _does_ at that Level. Branches carry no rubric (they roll up).
- Keep the tree a **monitor, not a to-do list**: name skills worth watching, not tasks.

## Process

1. **Read** the current Definition (when editing). Understand the existing branches
   and ids before changing them.
2. **Edit** — add, rename, remove, or restructure Skills; write or sharpen rubrics.
   Preserve unrelated nodes and their ids (renaming an `id` resets that Skill's saved
   progress).
3. **Validate** — a Definition that does not parse will blank the App. Run:
   ```bash
   node playbooks/author-skill-tree/scripts/validate.mjs <path-to-tree.yaml>
   ```
   It prints `OK …` or lists issues (duplicate ids, dangling parents, cycles, bad
   shape). Fix every issue and re-run until it passes.
4. **Report** back what changed — the Skills added/renamed/removed and the resulting
   structure — so the user can confirm.

## Completion

The Definition validates cleanly and reflects exactly what the user asked for, with
every new leaf carrying `3 / 6 / 9` behavioural anchors.