build-cs-skill

Purpose

Use this skill to turn a CodeStable skill into a small, recoverable, testable protocol. The output is either a new SKILL.md or a focused refactor plan for an existing cs-* skill.

The governing principle: SKILL.md is prompt-as-code — its quality is measured by behavior, recoverability, and testability, not by length.

Scope

Target skill roots:

• plugins/codestable/skills/<skill-name>/
• .claude/skills/<local-skill-name>/

Before changing a CodeStable skill, read the target SKILL.md and only the references needed for the current stage. Preserve user edits and existing compatibility entry points unless explicitly asked to remove them.

References

Load these files only when the current task needs that layer:

• references/cs-skill-spec-standard.md: read when writing or refactoring description, ## Spec, Haskell-style decision contracts, state models, failure behavior, or output contracts.
• references/cs-skill-quality-gates.md: read when reviewing a skill for prompt-as-code quality, P1/P3 separation, contracts, progressive loading, regression risk, or test-host safety.
• references/cs-skill-fixture-patterns.md: read when designing decision fixtures for routing, checkpoints, forbidden actions, failure paths, fastforward, or compatibility entries.

Spec

buildCsSkill :: SkillWorkRequest -> SkillWorkOutcome

data SkillWorkRequest = SkillWorkRequest
  { targetSkill  : Path
  , intent       : Create | Refactor | Simplify | Review | AddContracts | AddFixtures
  , userIntent   : UserIntent
  , targetRepo   : Path
  , constraints  : [Constraint]
  }

data RefactorDepth
  = MinimalHardeningPatch
  | FullProtocolRefactor

data ProcessProtocol
  = WorkflowProtocol
  | DomainProtocol
  | LifecycleProtocol
  | OperationProtocol
  | AlgorithmProtocol
  | ShimRoute
  | ReferenceOnly

data SkillKind
  = OperatorSkill       -- narrow trigger, concrete artifact, explicit state/branching
  | WorkflowSkill       -- orchestrates stages and loads references progressively
  | MethodologySkill    -- broad guidance; should expose an operator entry plus references
  | CompatibilityShim  -- passes legacy intent to one canonical skill
  | ReferenceDoc        -- no stable user -> artifact path; should not be an active trigger

data ValidationLayer
  = Shape | ContractSemantics | CrossFile | Scenario | RuntimeConformance | ForwardTest

data HostImpact = Hermetic | Isolated | LiveReadOnly | LiveMutating
data ResourceBudget = Light | HeavySerial

data ValidationPlan = ValidationPlan
  { layers         : [ValidationLayer]
  , hostImpact     : HostImpact
  , resourceBudget : ResourceBudget
  }

data SkillShape = SkillShape
  { trigger        : TriggerContract
  , entryPoint     : FunctionSignature
  , refactorDepth  : RefactorDepth
  , process        : ProcessProtocol
  , stateModel     : Maybe StateMachine
  , runtimeRouter  : Maybe RuntimeContract
  , outputContract : OutputContract
  , failureModes   : [FailureMode]
  , contracts      : [MachineContract]
  , fixtures       : [DecisionFixture]
  , validation     : ValidationPlan
  }

data SkillWorkOutcome
  = PatchApplied [Path]
  | RefactorPlan SkillShape
  | ReviewReport SkillShape
  | NeedsHuman Reason

selectRefactorDepth :: UserIntent -> RefactorDepth
selectRefactorDepth(intent)
  | explicitMinimal(intent) -> MinimalHardeningPatch
  | otherwise               -> FullProtocolRefactor

classifySkill :: SkillSource -> SkillKind
selectProcessProtocol :: SkillKind -> SkillSource -> ProcessProtocol
selectProcessProtocol kind source =
  case kind of
    WorkflowSkill
      | lifecycleDriven source -> LifecycleProtocol
      | otherwise              -> WorkflowProtocol
    OperatorSkill
      | algorithmic source -> AlgorithmProtocol
      | otherwise          -> OperationProtocol
    MethodologySkill -> DomainProtocol
    CompatibilityShim -> ShimRoute
    ReferenceDoc     -> ReferenceOnly

buildSkillShape :: SkillSource -> UserIntent -> SkillShape
validateSkillShape :: SkillShape -> ValidationReport

Workflow

1. Workspace safety

build-cs-skill creates or edits skill files; it does not execute a product CodeStable workflow. Do not require .codestable/attention.md just to author or refactor a skill.

Before editing, check git status in the target repository. Preserve unrelated user changes. Do not revert or move existing skill files unless explicitly requested.

When authoring an active cs-* skill that will run inside CodeStable projects, include that target skill's CodeStable preflight rule. The generated target skill should read .codestable/attention.md when it depends on project setup, repo state, artifact writes, or recoverability. That rule belongs in the target skill, not in build-cs-skill itself.

2. Choose refactor depth

Default to full protocol refactor unless the user explicitly asks for a minimal patch, a small additive change, or no behavior-preserving rewrite.

Use these labels exactly:

A change that only adds description exclusions, a small ## Spec, and machine contracts is a minimal hardening patch, not a full protocol refactor. If the user asked to refactor, simplify, or apply the build-cs-skill framework, produce a full protocol refactor or clearly state that the current proposal is only minimal hardening and ask whether to continue.

A full protocol refactor must include all of these, even when behavior is unchanged:

1. tightened frontmatter description;
2. ## Spec with entry function, request, state, outcome, and failure types;
3. process protocol appropriate to the skill kind;
4. explicit state restoration and next-action selection functions;
5. state machine mirrored as decision rules, not only left as a prose table;
6. progressive reference loading with allowed and forbidden loading behavior;
7. human checkpoint rules and non-bypass conditions;
8. failure behavior;
9. output contract;
10. machine contracts or recommended frontmatter contracts;
11. runtime alignment when a deterministic router / hook exists;
12. decision fixture recommendations.

3. Classify the skill

Classify the target before writing:

If a skill mixes kinds, split the active operator protocol from reference material instead of adding more prose.

4. Tighten the trigger

Write description as trigger + expected artifact/workflow + adjacent-skill exclusions. Avoid broad verbs alone (optimize, improve, analyze, help); use references/cs-skill-spec-standard.md for the boundary pattern.

5. Write the operator protocol first

Put execution-critical P1 content first: target preflight, entry intent, Spec, process, state restoration, checkpoints, failure, output. Workflow skills use a 5-7 step Workflow / Protocol / Lifecycle; operators use Operation / Algorithm; shims only pass intent; reference docs do not invent a workflow.

For target skills, include a preflight step when the skill touches .codestable/, scans repo state, writes artifacts, dispatches agents, or depends on project initialization. For pure formatting, routing shims, or reference-only materials, a separate preflight step is usually unnecessary.

For workflow skills, the process section should be shorter than the detailed decision rules and explain what the agent actually does from startup to recoverable exit. Do not replace it with only a type signature or only a routing table.

Cross-skill handoffs target the canonical main entry and let that skill restore state and select its own stage/lane. Only compatibility shims may pass an explicit legacy requested_stage / requested_mode preset.

Move long examples, templates, rationale, and pattern libraries to references/ or late sections. Do not let background material precede the protocol.

6. Make state recoverable

For workflow skills, define restoration from repository facts, not chat history:

repo facts -> state model -> next action

Every stage transition must leave durable evidence on disk, such as a status field, review artifact, checklist, result file, marker, or note. "The previous assistant said so" is not recoverable state.

For staged workflows, audit resume coverage end to end: every stage-level checkpoint answer must fit the canonical main entry's tagged resume domain and reach that stage unchanged. Every Awaiting outcome must persist a machine-readable state, reason, and external run id before returning, and the real router must restore them without chat memory.

The routing function must cover the complete lifecycle from trigger to exit — including entry (grill/intake), rebuild/degrade branches, iteration, checkpoints, and completion. Guard order is priority order; an unreachable tail branch is a bug. Measured: a model that keeps picking "the nearest enum" on one branch usually signals a missing guard, not bad wording (cs-goal rt-g02: two wording rounds 0.33→0.33, one added entry guard →0.89 — see quality-gates Measured Rules 6).

Haskell Contract Gate

When adding or changing a Haskell-style block, read references/cs-skill-spec-standard.md and apply its Haskell Contract Standard. A fence alone is not a contract. A branched protocol must expose its entry signature, closed decision domains, prioritized and exhaustive decision function, explicit invalid/blocked outcome, and path-wide invariants or termination rule when they affect completion. Keep rationale in comments; keep executable branches in equations. Do not retain a prose routing table as a second source of truth.

Runtime Alignment Gate

When the target has a deterministic router, hook, or state file schema, treat it as executable enforcement of the prompt Spec, not an independent routing truth. Align state names, normalization, guard priority, terminal-state precedence, and outcomes across SKILL.md, runtime code, persisted artifacts, and decision fixtures. Add a mechanical conformance test; a green grep contract or a separately hand-written test router is not sufficient. Detailed checks live in references/cs-skill-quality-gates.md.

7. Add progressive reference loading

State which reference file is loaded for each stage. The skill must not load all references at startup.

Use this wording when relevant:

Load exactly one stage protocol before acting, plus only the support files that protocol requests.

When a skill also loads project facts (CONTEXT.md, ADR, compound) across stages or batch fan-out, apply the Idempotent Context Loading Gate (references/cs-skill-quality-gates.md): reuse facts already loaded in-session instead of unconditional re-reads, and drive batch skips with a structural flag (e.g. reuse epic_child_batch), not wording.

8. Add machine contracts

If the local validation system supports frontmatter contracts, add contracts:. If it does not, still include a ## Machine Contracts section so the invariants are explicit and can later be wired into validation.

Good contracts protect behavior, not documentation: routing function names, required checkpoint / artifact phrases, progressive loading, and forbidden actions.

Do NOT anchor bare Spec type names (FeatureState, HumanCheckpoint, CheckpointReason) — they only prove the Spec block exists, not that any behavior is protected (measured; see quality-gates Contract Gate). Select terms that would be missing only if an important rule was lost. Avoid generic words like quality, check, best, or review.

9. Design decision fixtures

For important branch logic, write one-decision fixtures in the runnable eval-cs-skill schema under experiments/<skill>-routing-001/fixtures/routing/*.json; use references/cs-skill-fixture-patterns.md for shapes.

Oracle discipline: use result_type_any / target_any to accept semantically equivalent phrasings (older variants lack Spec vocabulary); spot-check observed answers before trusting a verdict.

Prioritize fixtures for: activation/routing; stage ordering; forbidden actions; human checkpoints; failure paths; fastforward or compatibility shortcuts.

10. Define failure behavior

Every skill must say what happens when it cannot safely continue. A good failure result includes the current artifact, blocking reason, next user action, files already written, and whether retry is safe.

Do not silently continue when approved scope, public contracts, data shape, or user-visible behavior would change.

For build-cs-skill itself, return NeedsHuman when the target/output is ambiguous, overlapping user edits cannot be preserved, behavior-equivalent constraints conflict with the required rewrite, or referenced protocols are missing. Route measured experiment requests to eval-cs-skill.

11. Keep the file small

Prefer a short SKILL.md plus references over a large always-loaded file. Rule of thumb: active protocol in the first 150-250 lines; examples and templates go to references; detailed rationale to docs; deterministic checks and repeated transformations to scripts.

12. Plan validation and verify

Create a ValidationPlan before running commands. Apply the Regression Ladder and Live Host Safety Gate in references/cs-skill-quality-gates.md: start with the cheapest hermetic layer, isolate integration state, and run heavy suites/builders serially. Never overlap full pytest, Go validation, multi-target builders, or package installs on a live developer host.

Tests must not stop, restart, archive, close, signal, or rewrite a host-managed agent service. Cleanup is limited to processes created by the current test and revalidated immediately before the signal; uncertain ownership means preserve the process and report the leak. If a required layer cannot respect those bounds, mark it unrun with the reason instead of weakening the safety gate.

Structural tests are necessary but not sufficient. After refactoring a core workflow/operator skill:

1. run structural tests, runtime-alignment conformance tests, and git diff --check;
2. re-check routing behavior via eval-cs-skill: routing-decision fixtures per Spec branch, >=2 models, k>=3, against a frozen pre-change variant snapshot;
3. triage failures in this order before blaming the skill: oracle too strict > fixture ambiguity > skill defect > model behavior difference;
4. cap live wording fixes at two rounds per fixture; wording-resistant failures signal a structural gap in the Spec (see quality-gates Measured Rules 6);
5. write conclusions back into references/cs-skill-quality-gates.md Measured Rules when they generalize.

CodeStable-specific shape patterns (main workflow skills, compatibility shims, fastforward modes, goal handoff) live in references/cs-skill-spec-standard.md.

Output Contract

build-cs-skill final responses must include: target skill path; classification; refactor depth (minimal hardening patch | full protocol refactor); files changed or planned (distinguishing actual edits from sample fixtures); validation result, or reason validation was not run; missing confirmations or maintainer decisions; next concrete action.

Report rewrites with the section-by-section structure in references/cs-skill-spec-standard.md (Review Report Template). If the output is not a full protocol refactor, explicitly name which required sections are missing and why. Keep unrelated product changes out of the skill rewrite unless the user explicitly asks for them.