Note graduation

Notes and skills hold different things. A note holds knowledge for a human to read; a skill holds a procedure for an agent to execute. When a note's real use has become "follow these steps every time," it has outgrown the vault - graduate it.

This skill is the pipeline the skills repo itself was built with.

Step 1: Confirm it should graduate

All three must hold; if any fails, leave it as a note:

1. Procedural - the note's core is steps to follow, not facts to know or stories to remember.
2. Repeated - the procedure has actually been followed at least twice; a procedure used once is still an experiment.
3. Stable - the steps stopped changing between uses; graduating a still-evolving procedure freezes it too early.

Step 2: Decide where it lives

• Used only inside one repo -> that repo's .claude/skills/<name>/SKILL.md, committed with the code.
• Used across projects -> the general skills repo (symlinked into ~/.claude/skills).
• When unsure, start repo-scoped and wait for a second consumer before generalizing - a wrong abstraction costs more than a duplicated procedure.

Never place skills inside an iCloud-synced vault: git and iCloud sync fight over the same files.

Step 3: Rewrite - do not copy

A note is narrative; a skill is imperative. The rewrite:

• Address the agent directly: numbered steps, explicit decision points ("if X, stop"), one action per step.
• Keep only what changes behavior; the note's stories and context stay behind in the vault.
• State the failure modes as rules, often as a "what this skill is not" section - the three ways the note's author has seen the procedure go wrong are the most valuable lines in the skill.
• Write the frontmatter description as one sentence covering what it does and when to invoke it: it is the only part loaded into every session, and it is what makes the skill fire at the right moment.

Step 4: Separate procedure from bindings

The published procedure must contain nothing personal; the personal parts resolve at runtime:

• Personal paths, names, and accounts -> resolve via an environment variable, then the user's global CLAUDE.md or memory, then ask once.
• Public conventions and opinions (a methodology like PARA, style rules) stay in the skill - opinions are the value, bindings are the leak.

Step 5: Leave a pointer, keep the note

The note does not get deleted. Add one line at its top: "Graduated to the <name> skill on <date>." From then on the note accumulates examples and war stories; the skill owns the procedure. If following the skill later reveals a better step, the fix goes to the skill - never back into the note.

Step 6: Test on a real case

Invoke the new skill on a real instance of the task and compare against how the user actually works. A skill that has never fired is a draft, not a graduation.