From 564f946471856044b44c39bf2ae7a16357eacca5 Mon Sep 17 00:00:00 2001 From: alexion Date: Sat, 5 Sep 2026 18:02:24 -0400 Subject: [PATCH] feat(skills): add craft-skill --- src/skills/.pi/skills/craft-skill | 1 + src/skills/craft-skill/GLOSSARY.md | 161 +++++++++++++++++++++++++++++ src/skills/craft-skill/SKILL.md | 117 +++++++++++++++++++++ 3 files changed, 279 insertions(+) create mode 120000 src/skills/.pi/skills/craft-skill create mode 100644 src/skills/craft-skill/GLOSSARY.md create mode 100644 src/skills/craft-skill/SKILL.md diff --git a/src/skills/.pi/skills/craft-skill b/src/skills/.pi/skills/craft-skill new file mode 120000 index 0000000..a7205e7 --- /dev/null +++ b/src/skills/.pi/skills/craft-skill @@ -0,0 +1 @@ +../../craft-skill \ No newline at end of file diff --git a/src/skills/craft-skill/GLOSSARY.md b/src/skills/craft-skill/GLOSSARY.md new file mode 100644 index 0000000..dfd7525 --- /dev/null +++ b/src/skills/craft-skill/GLOSSARY.md @@ -0,0 +1,161 @@ +# Glossary — Skill Craft + +This glossary defines the checks for [`craft-skill`](SKILL.md). +Each term is a lever on **predictability**. + +## Predictability + +The degree to which a skill makes the agent follow the same process on every run. +Predictability does not require identical output. +A brainstorming skill can predictably produce different ideas. + +## Invocation + +How the agent or operator reaches a skill. +Invocation controls who pays the load for discovery. + +### Model-invoked + +A skill that the harness exposes to the agent's available-skills list. +The agent can load it without an explicit operator command. +Use model invocation when the agent must discover the skill on its own. + +### User-invoked + +A skill that the operator runs deliberately through the harness invocation mechanism. +Use user invocation when human judgment decides when the skill applies. +For Pi, keep the required description and add `disable-model-invocation: true`. + +### Description + +Required metadata that states what the skill does and when to use it. +For model-invoked skills, the description carries the trigger condition. +For user-invoked skills, the description remains valid metadata. + +### Context pointer + +A short reference that tells the agent when to load out-of-context material. +The pointer's wording controls whether the agent reaches the target. +Fix weak wording before moving the target inline. +The description is the top-level context pointer for a model-invoked skill. +A link to a sibling reference file is a lower-level context pointer. + +### Context load + +The permanent attention cost of model-invoked skill descriptions. +More discoverable skills create more context load. +Use context load to decide whether a skill needs model invocation. + +### Cognitive load + +The memory cost that user-invoked skills place on the operator. +More user-invoked skills make the operator remember more names and uses. +Use cognitive load to decide whether a skill needs discoverability. + +## Information hierarchy + +How a skill ranks information by the moment the agent needs it. +Keep the active procedure above supporting reference. +Move branch-specific or large reference behind context pointers. + +### Steps + +Ordered actions that the agent performs. +Put steps in `SKILL.md` when the skill has an active procedure. +End each step with a completion criterion. + +### Reference + +Material that the agent consults while following steps. +Keep short reference near the step that needs it. +Move large or branch-specific reference to sibling files. + +### External reference + +Authoritative material that lives outside the skill directory. +Point to external reference instead of duplicating project policy. +Use it when another file owns the meaning. + +### Progressive disclosure + +Moving reference out of `SKILL.md` and behind a precise context pointer. +Use progressive disclosure to protect the skill's active procedure. +Keep must-read material inline when a pointer would miss too often. + +### Co-location + +Keeping a concept's rules, caveats, and examples near one another. +Use co-location so one read gives the agent the complete local meaning. +Do not scatter one concept across unrelated sections. + +## Steering + +How a skill shapes the agent's runtime behavior. +Steering turns a document into a repeatable process. + +### Branch + +A distinct path through a skill. +A branch handles a case that does not run the same steps as other cases. +Do not call ordinary checklist items branches. + +### Leading word + +A compact term that anchors a repeated behavior. +Prefer words already used by prompts, docs, or code. +Repeat the word, not the full explanation. + +### Completion criterion + +The condition that tells the agent a step is complete. +A strong completion criterion is checkable and demanding. +Use it to prevent early movement to the next step. + +### Legwork + +The work the agent performs inside a step. +Strong completion criteria increase legwork. +Weak criteria let the agent stop after surface-level work. + +### Post-completion steps + +The steps visible after the current step. +Visible later steps can pull the agent forward too early. +Hide later steps only when a real context boundary exists. + +## Failure modes + +Use these findings during audit and verification. +Quote the offending passage when a finding applies. + +### Premature completion + +A step ends before its necessary work is complete. +This usually comes from a vague completion criterion. +Fix the local criterion before splitting the skill. + +### Duplication + +One meaning has more than one authoritative expression. +Duplication increases maintenance cost and false emphasis. +Replace duplicates with one source and pointers to it. + +### Sediment + +Old content remains after the skill's behavior changes. +Sediment makes the agent attend to stale instructions. +Remove lines that no longer affect the skill's current behavior. + +### Sprawl + +`SKILL.md` contains too much live material. +Sprawl hides the active procedure among supporting details. +Move reference down the information hierarchy. + +### No-op + +An instruction does not change the agent's default behavior. +No-op instructions spend attention without adding control. +Judge no-op instructions against behavior, not style. +Delete a no-op sentence instead of shortening it. +Cut no-op sentences unless they anchor a target-project convention. diff --git a/src/skills/craft-skill/SKILL.md b/src/skills/craft-skill/SKILL.md new file mode 100644 index 0000000..c504cc5 --- /dev/null +++ b/src/skills/craft-skill/SKILL.md @@ -0,0 +1,117 @@ +--- +name: craft-skill +description: Draft or audit an Agent Skill for structural predictability. Run deliberately as /skill:craft-skill when creating or improving a skill. +disable-model-invocation: true +--- + +# craft-skill + +Draft or audit an Agent Skill. +Judge the skill against one bar: **predictability**. +Predictability means the agent follows the same process on every run. + +Read [`GLOSSARY.md`](GLOSSARY.md) before applying glossary terms. +Use this skill for skill structure, not general prose review. +Apply project writing rules when the target project defines them. + +## Choose the branch + +Use **Draft** when creating a new skill source. +Use **Audit** when reviewing an existing skill in its authoritative source. + +Finish when one branch matches the user's requested change. + +## Draft + +1. Resolve the destination. + Read the target project's instructions and skill-source conventions. + Prefer an existing source directory over a new convention. + Trace symlinks and generated placements to their source. + Ask the user when multiple writable sources remain plausible. + + Finish when the destination is writable and authoritative. + +2. Create the skill structure. + Create a directory whose name matches the skill name. + Add `SKILL.md` with valid Agent Skills frontmatter. + Add `disable-model-invocation: true` only for Pi user-invoked skills. + Add sibling files only when they protect the **information hierarchy**. + + Finish when the file layout matches the target harness and project. + +3. Write the skill body. + Put active **steps** in `SKILL.md`. + Keep shared **reference** near the steps that need it. + Move large or branch-specific reference behind precise **context pointers**. + Front-load the **leading word** in descriptions and other context pointers. + Write pointer text for the condition that loads the target. + Give each step a checkable **completion criterion**. + Cut sentences that do not change agent behavior. + Use relative paths for all skill-local references. + + Finish when each branch has ordered steps, resolved references, and checkable completion criteria. + +## Audit + +1. Locate the authoritative source. + Read the target project's instructions and skill-source conventions. + Inspect enabled-skill directories only to find the source. + Do not edit symlinks, generated files, installed packages, or vendored copies. + Ask the user when multiple sources claim the same skill. + + Finish when you have identified the authoritative source. + +2. Read the skill surface. + Read `SKILL.md` and every disclosed file. + Read project documents that the skill treats as authoritative. + Record which file owns each meaning before judging duplication. + + Finish when all referenced behavior is visible. + +3. Apply the checklist. + Quote each passage that fails a glossary check. + Check **invocation** against the intended harness. + Check **context pointers** for weak trigger wording. + Check **information hierarchy** for buried steps or disclosed required material. + Check **completion criteria** for vague or weak stopping points. + Check **leading words** for repeated explanations they can replace. + Check **pruning** for sentences that explain default model behavior. + Check **duplication**, **sediment**, **sprawl**, and **no-op** instructions. + + Finish when every finding has quoted evidence or no finding remains. + +4. Report or fix findings. + Report findings by default. + Fix findings only when the user requests edits. + Preserve behavior that passes the checklist. + Change only structural skill problems unless the user expands the scope. + + Finish when you have reported each finding or fixed each requested finding. + +## Verify + +1. Run deterministic checks. + Verify required frontmatter exists. + Verify the name is portable and matches the directory. + Verify the description is specific and under 1024 characters. + Verify every skill-local reference resolves with a relative path. + Verify context pointers name when to load referenced material. + Verify disclosed files exist. + Verify each retained sentence changes behavior or records target-project policy. + Verify no stale harness-specific assumption remains. + + Finish when each check passes or the final report names checks that could not run. + +2. Re-read against the glossary. + Re-check **invocation**, **information hierarchy**, and **completion criteria**. + Re-check **duplication**, **sediment**, **sprawl**, and **no-op** instructions. + Fix any new structural finding. + + Finish when no unresolved structural finding remains. + +3. Report the result. + List every changed path. + State whether you enabled the skill or only authored it. + Do not stage or commit unless the user requested it. + + Finish when the user can review the exact files changed. -- 2.47.3