Skill Management

Manage the lifecycle of custom managed skills in {workspaceDir}/skills.

When to Use

USE THIS SKILL WHEN:

• The user says "build me a skill" or "create a skill for X"
• The user wants to scaffold, edit, or delete a SKILL.md in their workspace
• The user wants a repeatable workflow captured as an invocable skill

Do NOT use this skill when the user just wants to run an existing skill. That is normal activation, not management.

Capabilities

• Scaffold a new managed skill with YAML frontmatter and markdown body
• Edit an existing skill by scaffolding over it (replaces the body and needs activation_hints restated; every other frontmatter field you leave out keeps its current value, and an empty value clears one)
• Delete an existing managed skill directory

Skills created via scaffold_managed_skill become available for skill_load when a valid top-level SKILL.md is written under the skill directory.

Step 1 - Align with the user before building

Ask before doing anything. Do not scaffold a skill until you have confirmed with the user:

• What the skill should do
• When it should activate (the trigger phrases, in their words)
• The major steps it performs
• Any destructive steps and the done condition

✓ Checkpoint: Have you confirmed scope with the user? If you are guessing at any of the four points above, ask first. Do not scaffold on assumption.

Step 2 - Write a description AND activation-hints, always both

The description is what makes the skill discoverable. It must cover both what the skill does and when to reach for it, phrased the way the user would say it.

description: Build anything visual — apps, landing pages, dashboards, trackers,
  calculators, games, tools, slide decks, or data visualizations. Use whenever
  the user wants something built that they can see and interact with.

Every skill must also ship activation-hints in its frontmatter. This is not optional. Keep activation-hints separate from the description: the description sells the skill, the hints list the concrete trigger phrases the user confirmed in Step 1.

metadata:
  vellum:
    activation-hints:
      - "build me an app"
      - "make a dashboard"
      - "create a landing page"

✓ Checkpoint: Does the frontmatter have both a description and an activation-hints list? If hints are missing, go back and add them before writing the body.

Step 3 - Structure the body so it survives weak models

Strong models tolerate loose structure. Weaker models drift. Build every body with these patterns.

Open with a ## When to Use block. User language, not jargon. This is what makes the model recognize when the skill applies.

Put critical warnings at the point of action. A warning at the top of a file is forgotten by the time the model is 200 lines deep. Do not trust the top-of-file warning. Repeat the danger where the dangerous action happens.

## Step 5 - Apply the JSON blob

⚠️ CRITICAL: Use the complete blob below. Setting even one key
wipes the entire block. Copy the whole thing or fail.

Add explicit checkpoints between major steps, sparingly. Long executions blur together. The model finishes step 3 and slides into step 4 without re-anchoring. A checkpoint forces a re-read. Use them between major sections, not on every step.

Make branching explicit with If / →, and always name the default. Prose hides decisions. The model reads linearly and walks past a branch without registering it. Every If must cover the default case. Implicit fall-through ("otherwise figure it out") creates drift.

If the user already has a draft → restructure it into the template.
If not → build the steps from their description (default).

Step 4 - Define done by binding tool calls to artifacts

Without an explicit done condition, the model invents one. It stops too early ("the file was created, done") or overshoots ("let me add one more feature"). Both are drift.

Each completion criterion must bind a tool call to the user-visible artifact it produces. Do not write criteria the model can satisfy by narration alone.

## SKILL COMPLETE WHEN

- [ ] `scaffold_managed_skill` wrote the SKILL.md and returned its path
- [ ] User confirmed the skill loads via `skill_load`
- [ ] User saw the trigger phrases that will activate it

✓ Checkpoint: Before scaffolding, confirm the body has a ## When to Use block, point-of-action warnings on any dangerous step, explicit If / → branches with named defaults, and artifact-bound completion criteria.