Skill Guidance

AUDITS a skill/repo and SPECS the build, emitting skill-engineer's handoff spec (stage 1). Use when asked if a skill is good/industrial-grade, needs scoring/scope/missing-pieces, or pointed at a SKILL.md before build: "$skill-guidance". It PLANS only; not build (engineer), compress (zipper), or full loop (conductor).

Apply industrial skill-design principles to a target skill and emit a machine-handoff spec that the next stage (skill-engineer) builds from. This skill plans and evaluates — it does not build.

The deliverable is a structured spec file. But a spec is only as good as its context, so this skill is not silently autonomous: it runs a context-sufficiency gate (Step 6, rules/elicitation.md) and asks when the input leaves a decision-critical gap — minimize but never suppress. Never bury a guess in blocking_unknowns (this skill's #1 failure): ask a present human, or in a pipeline run log an explicit assumption — never block.

Backing knowledge base

Ground every judgment in the local develop-principle KB (default ../../develop-principle, at the repo root) — not memory; load rules/kb-grounding.md for the query commands and the 7 pillars (design, research, testing, tdd, metrics, low_context_kb, lifecycle) the scorecard scores against.

Steps

Step 1 — Resolve and read the target

Accept a SKILL.md path or a repo path (both supported; a "blank idea" arrives as a thin/stub SKILL.md — that is normal input, not an error). If a repo, find its SKILL.md (and note sibling rules/ scripts/ references/ assets/ evals/).

Multiple SKILL.mds: pick the one whose parent dir best matches the repo/worktree name; treat fixture dirs (dogfood-*, fixtures/, test-*, examples/) as input data, not targets; if still ambiguous, evaluate the highest-content one and note the rest in blocking_unknowns. Record your choice.

Run the deterministic signal pass:

bash

node scripts/score_skill.mjs <skill-dir | SKILL.md path>

Capture its JSON: maturity_hint, dirs, signals, pillar_hints. These are evidence seeds, not verdicts — you refine them.

If score_skill.mjs exits non-zero (no SKILL.md), stop: refuse ("no SKILL.md found at <path>"), write no spec, suggest skill-creator. Don't proceed.

Step 2 — Detect intent and maturity

Load rules/intent-and-maturity.md. From the frontmatter + body, state what the skill is for, its in/out-of-scope, primary user, and observed triggers. Settle maturity (stub | draft | mature) — it drives altitude in Step 5.

Step 3 — Score the 7-pillar readiness scorecard

Load rules/scorecard.md. For each pillar, pull the canonical criteria from the KB (query_kb), judge present | partial | absent (0/1/2), cite evidence from the target, and list concrete gaps. Sum to an overall readiness (x/14) and a verdict (draft | candidate | industrial).

Step 4 — Light comparable-design research

Load rules/comparables.md. Pick 1–2 comparable real skills, fetch them, and extract transferable structure (triggers, modules, tests) — the "资料搜集" step. Light at lite altitude, fuller at full. Learn patterns; never copy.

Step 5 — Decide altitude

Load rules/altitude.md. Choose lite vs full from stakes × maturity × surface area. Industrial ≠ always-heavy — it means right rigor for the stakes; don't force a small utility through full research + metrics + lifecycle ceremony.

Step 6 — Context-sufficiency gate (elicit before emit)

Load rules/elicitation.md. Run node scripts/detect_context_gaps.mjs <target>; for each missing slot write one targeted, domain-specific question to <target>/.skill-guidance/clarifying-questions.json (ask a present human via AskUserQuestion; in a pipeline run, log an explicit assumption per gap). If the detector says sufficient:true, do not manufacture questions. Never dump gaps into blocking_unknowns. This gate makes the spec concrete enough to build/test.

Step 7 — Emit the machine-handoff spec

Load rules/spec-format.md and the contract assets/handoff-spec.schema.json. Write the filled spec to <skill-dir>/.skill-guidance/handoff-spec.json (create the dir; it sits beside the target, not inside this skill). It captures intent, the scorecard, gaps, a recommended design across all 8 design units, the altitude call, prioritized actions, and handoff.next_skill = "skill-engineer". The spec is the real output; optionally print a 3-line summary (verdict+ratio, top 1–2 P0 actions, blocking_unknowns count).

Modules

File	When to load
rules/kb-grounding.md	Before Step 1 (and any pillar query) — the develop-principle KB query commands and the 7 pillars to ground judgments in.
rules/intent-and-maturity.md	Step 2 — how to read intent and classify stub/draft/mature, and how maturity maps to altitude.
rules/elicitation.md	Step 6 — the context-sufficiency gate: detect gaps, phrase one targeted question per missing slot, ask (standalone) vs log-assumption (pipeline), never dump into blocking_unknowns.
rules/scorecard.md	Step 3 — the 7-pillar rubric, the KB query per pillar, and present/partial/absent definitions.
rules/comparables.md	Step 4 — how to pick, fetch, and mine comparable skills from the registry; when to skip at lite altitude.
rules/altitude.md	Step 5 — the lite-vs-full decision and what each altitude includes/skips.
rules/spec-format.md	Step 6 — field-by-field meaning of the handoff spec and how to fill it.

Scripts

File	Usage
scripts/score_skill.mjs	node scripts/score_skill.mjs <skill-dir | SKILL.md> — deterministic structural signals (frontmatter, dirs, size, per-pillar hints, maturity). Seeds the scorecard.
scripts/detect_context_gaps.mjs	node scripts/detect_context_gaps.mjs <target | --idea "..."> — flags decision-critical slots the input leaves open (the elicitation trigger seed). --selftest proves it discriminates.

Assets

File	Usage
assets/handoff-spec.schema.json	The JSON contract for the spec skill-engineer consumes. The spec you emit must conform.
assets/handoff-spec.example.json	A filled example to copy the shape from.