learn-skill

learn-skill

Turn a learning from this session into a durable skill. The defining rule of this skill is location safety: skills in protected locations (the home folder) are treated as read-only. All create / migrate / update operations land in the project-local target so a machine-wide skill is never silently mutated.

Configuration

config.json (next to this file) controls behavior. The helper script reads it; never hard-code paths.

Integrations are doubly gated: an integration is used only if its flag is true AND the package is installed. Run detect to see effective state; if a helper isn't installed, skip it silently — never fail because of it.

bun .pi/skills/learn-skill/scripts/skillctl.ts detect

Workflow

Run all commands from the project root (so cwd is the project whose .pi/skills should receive the skill). Use bun — it is the repo runtime.

1. Decide what is worth capturing

Only capture a learning that is reusable and non-obvious: a multi-step workflow, a fix for a recurring failure, an exact command sequence, an environment gotcha, or a convention. Skip one-off facts and anything already covered by an existing skill. Name it as lowercase-hyphenated (≤64 chars).

If integrations.useTodo is active and the capture spans multiple skills or steps, track the work with the todo tool. If integrations.useAskUserQuestion is active and the skill's name, scope, or trigger conditions are ambiguous, ask the user before writing rather than guessing.

1b. Dedup check (when features.dedup)

Before creating anything new, look for an existing skill that already covers this:

bun .pi/skills/learn-skill/scripts/skillctl.ts similar <keywords...>

If a strong overlap exists, prefer updating that skill (step 3b) over creating a near-duplicate. Use plan for a full dry-run that combines the resolved action, dedup hints, and active integrations without writing anything:

bun .pi/skills/learn-skill/scripts/skillctl.ts plan <skill-name> <keywords...>

2. Resolve the write action

bun .pi/skills/learn-skill/scripts/skillctl.ts resolve <skill-name>

This prints one of:

• create — no skill by that name exists → create it under target.
• update — a local skill exists → edit it in place.
• migrate — only a protected (home) skill exists → copy it local, then edit the copy.
• update-protected — only appears when allowProtectedWrites: true.

Use list / locate to inspect first if unsure:

bun .pi/skills/learn-skill/scripts/skillctl.ts list
bun .pi/skills/learn-skill/scripts/skillctl.ts locate <skill-name>

3a. CREATE

Write <target>/<skill-name>/SKILL.md with valid frontmatter (name, description) and a concise body. The description must state what it does and when to use it — this is what triggers loading later. Add scripts/ or references/ only if needed.

• If integrations.useArgs is active and the skill takes input (a target, an env, a name), author it with $1 / $ARGUMENTS / $@ placeholders so it works as /skill:<name> <args>.
• If features.crossLink is active, add a short "See also" / "Next step" line pointing to related skills surfaced by the dedup/similar check.

3b. UPDATE (local)

read the existing local SKILL.md and fold the new learning in surgically — extend the relevant section, tighten the description if the trigger conditions widened. Do not rewrite wholesale.

3c. MIGRATE (protected → local), then update

bun .pi/skills/learn-skill/scripts/skillctl.ts migrate <skill-name>

This copies the protected skill directory into target and leaves the original untouched. Then apply step 3b to the local copy. Never edit the protected source.

3d. Modularize (when features.modularize)

Keep skills small and composable. Run the audit on the skill you just wrote/updated:

bun .pi/skills/learn-skill/scripts/skillctl.ts audit <skill-name>

Act on what it reports, across three axes:

1. Progressive-disclosure split — if the body exceeds maxBodyLines, move detail (long examples, reference tables, edge-case notes) into references/*.md and leave the SKILL.md body lean (what + when + entry steps, linking the references). Only the description is always in context, so a lean body is cheaper and triggers better.
2. Shared partials — if the audit lists duplicate-block candidates, extract the shared content into <target>/<sharedDir>/<topic>.md (a plain markdown module, not a skill — no frontmatter, so it is never discovered as one) and link it from each skill instead of copying. One source of truth for cross-cutting policy (e.g. location safety, frontmatter rules).
3. Composable sub-skills — if a skill covers 2+ distinct concerns, split it into smaller skills that each do one thing and cross-link (step 3a's crossLink rule). If they form a pipeline and rpiv-workflow is installed, they can later be chained as /skill:<name> stages.

Location safety still applies: write partials under the local target and edit only local copies — never touch protected/home skills.

4. Validate (and optionally review)

bun .pi/skills/learn-skill/scripts/skillctl.ts validate <target>/<skill-name>

Fix any reported errors (name rules, description present + ≤1024 chars). A skill with a missing description will not load.

If integrations.useAdvisor is active, hand the drafted skill to the advisor tool for a second opinion before finalizing, and fold in any correction.

5. Report

Tell the user the action taken, the final path, and a one-line summary of what was captured. A newly written skill is discovered on the next session scan; within this session you can read it directly.

Guardrails

• Never write to or edit a path under protectedLocations unless allowProtectedWrites is explicitly true. When in doubt, migrate.
• Prefer updating an existing skill over creating a near-duplicate.
• Keep skills focused — one capability per skill. Split rather than bloat.
• If nothing in the session meets the "reusable and non-obvious" bar, capture nothing and say so.
• Integrations are optional: if a configured helper isn't installed, skip it silently — a missing extension must never block a capture.