Load mahou:basics first. Then read .mahou/learn.md if present.
Turns a session that worked into something reusable. The plugin grows this way, by keeping what the user just did by hand instead of designing a pipeline upfront.
Two modes
Route on the arguments.
- No arguments. Discovery. Follow
references/discover.md. Reconstruct the session, summarize it back, give a take, and wait for the user to pick what to keep.
- Arguments given. Directed. Follow
references/directed.md. No summary and no take. The user has said what they want. Map the state their ask touches and work toward it.
Both modes continue with Drafting once there is an item to draft.
Fidelity
Anything produced here reproduces the patterns the session established exactly. The formats, the visualizations, the wording of a rule, the order of steps, and every correction the user made along the way are the specification. Do not adapt them, improve them, or generalize them into something the session did not do.
Examples inside a skill or wiki entry are generic. They carry the shape the session used, with placeholders in place of the session's tickets, repositories and field names.
Drafting
Classify and scope each item before drafting it. Process becomes a skill, new or iterated. Work a skill should hand to a subagent becomes an agent. Knowledge about a tool or technology becomes a wiki entry. A decision the user repeated for this project becomes a standing rule in a local file. Global means useful in any project; local means true only for this one. Restate the job the item does, which kind it is and where it lands. Read the skill, entry or index it would land in to check it is not already there; if it already says this, the finding becomes an iteration on whatever failed to read it. Draft only once the user confirms the shape.
Draft one item at a time, ordered by confidence then by impact, waiting for the user's call on each. Never batch them into a single approve-everything question.
- A new skill: the full draft, following the new skill checklist.
- A skill iteration: the exact change and the reason it is needed.
- An agent: the full draft, plus the change to the skill that dispatches it.
- A wiki entry: the draft plus its line in the index at the right level.
- A local file: the draft and which skill it changes.
Write each approved item to its place. Leave everything uncommitted.
Where things land
| Finding |
Lands as |
| Reusable process |
skills/<name>/SKILL.md in the plugin |
| Work a skill should hand to a subagent |
agents/<name>.md in the plugin, dispatched by the skill that needs it |
| Knowledge about a tool or technology |
skills/wiki/references/<topic>/<entry>.md, plus its line in that folder's INDEX.md |
| A design type that generalizes beyond the session it came from |
skills/design/references/types/<type>.md, plus its row in the types table of mahou:design. A type specific to one change stays out |
| A rule or fact true only for this project |
.mahou/<skill>.md, or .mahou/wiki/ with the same index-per-level shape as the global store |
New skill checklist
- A descriptive name. The magic vocabulary stays in mahou:basics and the README.
- One job. Two jobs means proposing two skills.
- A description precise enough to load when intended, and to let mahou:guide match goals to it. Descriptions that overlap an existing skill's are the main way routing degrades.
- First lines of the body: load mahou:basics, then read
.mahou/<skill>.md if present.
- No decisions delegated to the agent. It maps the state and asks; the user settles. A draft that contains "choose the best option" or "decide whether" is not ready.
- Nothing committed as a side effect.
Removing or replacing a skill
When an item replaces an existing skill, the replacement is not done until the old directory is removed and every reference to it is updated: the plugin README and every skill that names it. List those edits as part of the item.
Committing
Propose, never commit. When the user accepts an item, write the files and stop. Version bumps belong to whatever commits the marketplace; never hand-edit a plugin.json version.
1---2name: learn3description: The author's tool for growing the plugin from real sessions. Without arguments it reconstructs the session, gives a take on where it departed from the existing skills, and drafts what the user picks. With arguments it skips the reconstruction and works the user's ask from the current context. Produces new or iterated skills, agents, wiki entries and local .mahou files.4---56Load mahou:basics first. Then read `.mahou/learn.md` if present.78Turns a session that worked into something reusable. The plugin grows this way, by keeping what the user just did by hand instead of designing a pipeline upfront.910## Two modes1112Route on the arguments.1314- **No arguments.** Discovery. Follow `references/discover.md`. Reconstruct the session, summarize it back, give a take, and wait for the user to pick what to keep.15- **Arguments given.** Directed. Follow `references/directed.md`. No summary and no take. The user has said what they want. Map the state their ask touches and work toward it.1617Both modes continue with Drafting once there is an item to draft.1819## Fidelity2021Anything produced here reproduces the patterns the session established exactly. The formats, the visualizations, the wording of a rule, the order of steps, and every correction the user made along the way are the specification. Do not adapt them, improve them, or generalize them into something the session did not do.2223Examples inside a skill or wiki entry are generic. They carry the shape the session used, with placeholders in place of the session's tickets, repositories and field names.2425## Drafting26271. **Classify and scope each item before drafting it.** Process becomes a skill, new or iterated. Work a skill should hand to a subagent becomes an agent. Knowledge about a tool or technology becomes a wiki entry. A decision the user repeated for this project becomes a standing rule in a local file. Global means useful in any project; local means true only for this one. Restate the job the item does, which kind it is and where it lands. Read the skill, entry or index it would land in to check it is not already there; if it already says this, the finding becomes an iteration on whatever failed to read it. Draft only once the user confirms the shape.28292. **Draft one item at a time**, ordered by confidence then by impact, waiting for the user's call on each. Never batch them into a single approve-everything question.3031 - A new skill: the full draft, following the new skill checklist.32 - A skill iteration: the exact change and the reason it is needed.33 - An agent: the full draft, plus the change to the skill that dispatches it.34 - A wiki entry: the draft plus its line in the index at the right level.35 - A local file: the draft and which skill it changes.36373. **Write each approved item** to its place. Leave everything uncommitted.3839## Where things land4041| Finding | Lands as |42|---|---|43| Reusable process | `skills/<name>/SKILL.md` in the plugin |44| Work a skill should hand to a subagent | `agents/<name>.md` in the plugin, dispatched by the skill that needs it |45| Knowledge about a tool or technology | `skills/wiki/references/<topic>/<entry>.md`, plus its line in that folder's `INDEX.md` |46| A design type that generalizes beyond the session it came from | `skills/design/references/types/<type>.md`, plus its row in the types table of mahou:design. A type specific to one change stays out |47| A rule or fact true only for this project | `.mahou/<skill>.md`, or `.mahou/wiki/` with the same index-per-level shape as the global store |4849## New skill checklist5051- A descriptive name. The magic vocabulary stays in mahou:basics and the README.52- One job. Two jobs means proposing two skills.53- A description precise enough to load when intended, and to let mahou:guide match goals to it. Descriptions that overlap an existing skill's are the main way routing degrades.54- First lines of the body: load mahou:basics, then read `.mahou/<skill>.md` if present.55- No decisions delegated to the agent. It maps the state and asks; the user settles. A draft that contains "choose the best option" or "decide whether" is not ready.56- Nothing committed as a side effect.5758## Removing or replacing a skill5960When an item replaces an existing skill, the replacement is not done until the old directory is removed and every reference to it is updated: the plugin README and every skill that names it. List those edits as part of the item.6162## Committing6364Propose, never commit. When the user accepts an item, write the files and stop. Version bumps belong to whatever commits the marketplace; never hand-edit a `plugin.json` version.
asermax