learned-docs_skill

Overview

This skill helps write, modify, and reorganize documentation under docs/learned/. It enforces frontmatter rules, category placement, index updates, and routing table changes so documentation remains discoverable and agent-friendly. Use it to create new docs, move files, or ensure generated indexes and AGENTS.md stay consistent.

How this skill works

The skill scans markdown files in docs/learned/, validates required YAML frontmatter fields (title, read_when), and checks category placement against the master index. It guides updates to category index.md files, cross-references, and AGENTS.md routing entries, and advises running doc sync and validation commands to catch formatting or link errors.

When to use it

• Creating a new document under docs/learned/
• Updating or adding frontmatter (title, read_when, tripwires)
• Moving files between categories or to root level
• Adding or updating index.md files for a category
• Updating AGENTS.md routing entries

Best practices

• Always include title and 2–4 specific gerund-style read_when conditions
• Place docs in the most relevant category; put unclear topics at root until patterns emerge
• Never embed Python functions or implementation code that processes erk data
• Use prose, CLI commands, or source file pointers instead of executable examples
• Run erk docs sync and make fast-ci after changes to regenerate and validate

Example use cases

• Add a new guide about CLI output formatting and include read_when: "styling CLI output"
• Move several related root docs into a new category after three related files accumulate
• Update a document's path and run grep to update cross-references, then refresh indexes
• Add an entry to AGENTS.md for a high-frequency task so agents can route correctly
• Remove Python processing functions from docs and replace with a source pointer and CLI example