145 lines
7.1 KiB
Markdown
145 lines
7.1 KiB
Markdown
---
|
|
name: design-skill
|
|
description: Draft a new Agent Skill, or audit and rewrite an existing one for structural predictability. Run deliberately as /skill:design-skill when designing or improving a skill, never automatically.
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# design-skill
|
|
|
|
Judge only structural **predictability** using the terms in [`GLOSSARY.md`](GLOSSARY.md).
|
|
Do not expand the work into general prose, safety, or technical review.
|
|
Read each relevant definition before applying it.
|
|
|
|
## Select the branch
|
|
|
|
Use **Draft a new skill** when the request describes a new capability or repeated process with no existing skill to modify.
|
|
Use **Audit an existing skill** when the request names an existing skill to review, fix, or improve.
|
|
|
|
Both branches end at **Verify**.
|
|
|
|
## Draft a new skill
|
|
|
|
### 1. Capture intent
|
|
|
|
Extract every answer already settled by the conversation or target project before asking anything.
|
|
Ask one question at a time only for missing decisions:
|
|
|
|
- Is the skill a **procedure**, **reference**, or both?
|
|
- Should it be model-invoked or user-invoked?
|
|
Walk the **context load** and **cognitive load** trade-off rather than defaulting.
|
|
- What distinct **branches** take genuinely different paths?
|
|
- Does project documentation already own any required material?
|
|
Point to that **external reference** instead of duplicating it.
|
|
- What checkable **completion criterion** ends each step?
|
|
- Does the project already use a **leading word** for the behavior?
|
|
|
|
Done when every item is settled or the user explicitly asks for a draft to iterate on.
|
|
|
|
### 2. Resolve the canonical source
|
|
|
|
Read the target project's instructions and inspect its repository structure before choosing a destination.
|
|
Prefer an existing Agent Skills source convention.
|
|
For a project-specific skill, use the project's canonical project-local skill source.
|
|
For a general skill, use the personal collection named by the user or project instructions.
|
|
|
|
Do not edit generated, installed, vendored, or compatibility surfaces as source.
|
|
When the discovered skill is a link or generated placement, trace it to its canonical source.
|
|
If multiple plausible sources remain, ask which one owns the skill.
|
|
|
|
Done when the destination is writable, authoritative, and inside the intended project or collection.
|
|
|
|
### 3. Write the skill
|
|
|
|
Use the Agent Skills standard as the baseline:
|
|
|
|
- Put the skill in a directory containing `SKILL.md`.
|
|
- Give the frontmatter a valid `name` and a specific `description`.
|
|
- Use documented harness extensions only when the target environment supports them.
|
|
- Keep paths relative to the skill directory.
|
|
|
|
Follow the **information hierarchy**.
|
|
Keep ordered **steps** in `SKILL.md`, keep reference needed by every branch nearby, and disclose branch-specific or extensive reference through precise pointers.
|
|
Reuse authoritative project documentation rather than restating it.
|
|
Every branch must have a complete path, every step must have a checkable completion criterion, and every sentence must pass the **no-op** test.
|
|
|
|
Done when the skill conforms to the target project's conventions and every captured decision has one authoritative expression.
|
|
|
|
## Audit an existing skill
|
|
|
|
### 1. Locate and read it
|
|
|
|
Read the target project's instructions and locate the named skill's canonical source.
|
|
Trace generated or linked placements rather than editing them.
|
|
Ask only when multiple plausible sources remain.
|
|
Read `SKILL.md`, every disclosed file, and any project documentation it treats as authoritative.
|
|
|
|
Done when the full design and every source-of-truth boundary are visible.
|
|
|
|
### 2. Apply the predictability checklist
|
|
|
|
Check every relevant definition in `GLOSSARY.md` and quote the exact offending passage for each finding:
|
|
|
|
- **Premature completion**: does each step end on a checkable criterion demanding all required work?
|
|
- **Duplication**: does any meaning have more than one source of truth?
|
|
- **Sediment**: does any sentence no longer bear on the skill's behavior?
|
|
- **Sprawl**: should reference be disclosed or a genuine branch be separated?
|
|
- **No-op**: does each sentence change model behavior from the default?
|
|
- **Invocation**: does the chosen invocation mode fit actual use and target-harness support?
|
|
- **Leading word**: can repeated explanation collapse into established vocabulary?
|
|
|
|
Judge sentence by sentence rather than line by line.
|
|
A line may contain both a load-bearing sentence and a no-op sentence.
|
|
|
|
Done when every glossary failure mode has been checked and every finding has quoted evidence.
|
|
|
|
### 3. Rewrite it
|
|
|
|
Rewrite the canonical source to address every finding.
|
|
Preserve intentional behavior that passed the checklist.
|
|
Follow target-project instructions for any change outside the skill directory.
|
|
|
|
Done when every finding is fixed or explicitly retained with a structural reason.
|
|
|
|
## Verify
|
|
|
|
### 1. Run deterministic checks
|
|
|
|
Run the target project's required checks and any available Agent Skills validator.
|
|
At minimum, verify frontmatter, naming, relative references, disclosed-file existence, and invocation compatibility with the target harness.
|
|
|
|
Done when every available deterministic check passes and every unavailable check is reported.
|
|
|
|
### 2. Smoke-test behavior
|
|
|
|
Derive one realistic task prompt from the skill's intended trigger phrasing.
|
|
Launch a fresh context through an actual subagent tool or documented headless harness command, load the skill there, and run the prompt.
|
|
The fresh context must attempt the target skill's task rather than design or audit that skill.
|
|
Save the exact prompt and fresh-context output in temporary files outside the target project.
|
|
Inspect that output for whether the agent followed the intended branch, hesitated, misread an instruction, or behaved unexpectedly.
|
|
Do not count the current design run, a self-review, or deterministic validation as behavioral evidence.
|
|
A smoke test does not require advance approval.
|
|
|
|
Done when the final report names the fresh-context mechanism and both evidence paths, and the captured output shows no structural confusion.
|
|
If no isolated execution mechanism exists, report that limitation instead.
|
|
|
|
### 3. Offer stronger verification when available
|
|
|
|
Detect whether the target project has an established behavioral test or benchmark convention for skills.
|
|
Use existing persistent tests when present.
|
|
Create a persistent test only when project instructions require one.
|
|
|
|
Before running a stochastic, repeated, paid, or otherwise substantial benchmark, show the user the proposed scenario and obtain approval.
|
|
If approval is declined, retain the smoke-test result as the weaker evidence level.
|
|
|
|
Done when an approved benchmark passes, the user declines it, or no established benchmark exists.
|
|
|
|
### 4. Re-audit and finish
|
|
|
|
Re-read the final skill against every applicable `GLOSSARY.md` failure mode in light of verification.
|
|
Fix every new finding and repeat affected checks after a substantial fix.
|
|
Follow explicit user or project instructions for staging or other version-control actions.
|
|
Otherwise leave changes unstaged and report every changed path.
|
|
Never commit unless explicitly instructed.
|
|
|
|
Done when no structural finding remains, required checks pass, behavioral confidence is stated accurately, and the applicable version-control policy was followed.
|