/build-cs-skill

name: build-cs-skill
description: "CodeStable skill authoring and evolution protocol. Use when creating, refactoring, simplifying, or reviewing cs-* skills under plugins/codestable/skills or .claude/skills. Produces a thin harness, an explicit context plan, evidence gates, and an optional agent collaboration contract. Do not use for product implementation; use eval-cs-skill only for measured experiment loops."

build-cs-skill

Purpose

Build the smallest always-loaded control surface that lets an agent select relevant context, respect hard gates, collaborate safely, and leave recoverable evidence. `SKILL.md` is the **thin harness**; references and repository facts are **thick context**. Thick means decision-useful, not large.

Specify responsibility, authority, context selection, evidence, and stop conditions. Leave safe implementation choices to the executing agent.

Scope And References

Targets are `plugins/codestable/skills/<skill-name>/` or `.claude/skills/<local-skill-name>/`.

Load only the reference needed for the current decision:

• `references/cs-skill-spec-standard.md`: contract definitions, typed decisions, recovery, and output semantics.
• `references/cs-skill-quality-gates.md`: review algorithm for placement, context, evolution, runtime alignment, and validation safety.
• `references/cs-skill-fixture-patterns.md`: risky routing, checkpoint, failure, compatibility, or

forbidden-action scenarios.

Spec

data SkillKind
  = OperatorSkill | WorkflowSkill | MethodologySkill | CompatibilityShim | ReferenceDoc

data SkillShape = NoActiveSkill | ThinOperator | ContextualWorkflow | ToolBackedWorkflow
                | ShimSkill | ReferenceSkill
data ProcessProtocol = WorkflowProtocol | DomainProtocol | LifecycleProtocol
                     | OperationProtocol | AlgorithmProtocol | ShimRoute | ReferenceOnly
data RulePlacement = Harness | StageContext | ProjectContext | DeterministicGate | Remove
data DelegationRole = Orchestrator | LeafExecutor

selectSkillShape :: SkillKind -> SkillSource -> SkillShape
selectSkillShape kind source | not (independentSkillNeeded kind source) = NoActiveSkill
selectSkillShape kind source =
  case kind of
    ReferenceDoc      -> ReferenceSkill
    CompatibilityShim -> ShimSkill
    OperatorSkill     -> ThinOperator
    WorkflowSkill
      | deterministicRouter source -> ToolBackedWorkflow
      | otherwise                  -> ContextualWorkflow
    MethodologySkill  -> ContextualWorkflow

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

placeRule :: Rule -> RulePlacement
placeRule r
  | mechanizable r                                    = DeterministicGate
  | nonMechanizableSafety r                           = Harness
  | projectSpecific r                                 = ProjectContext
  | stageSpecific r                                   = StageContext
  | everyInvocationNeeds r && changesDecisionOrGate r = Harness
  | otherwise                                         = Remove

buildContextPlan :: SkillShape -> [PlacedRule] -> ContextPlan
buildThinHarness :: SkillShape -> ResponsibilityContract -> ContextPlan -> Markdown

Build Protocol

1. Establish scope and responsibility

Read the target and relevant repository design facts; inspect git status and preserve unrelated edits. State the one outcome the skill owns, its authority boundary, completion evidence, and unsafe stop conditions. Authoring itself does not require project preflight. A generated skill adds preflight only when its behavior depends on project setup, repository facts, artifact writes, or recovery.

If there is no independent installable responsibility, or an existing skill/reference/tool owns it, select `NoActiveSkill`. A retired v1 CodeStable name also selects `NoActiveSkill`; migration prose is not an instruction to recreate a compatibility shim. Use `ReferenceSkill` only when knowledge has an independent distribution contract.

2. Choose the minimum shape

Classify before writing; do not default to a full protocol refactor. Use `ThinOperator` for one action/artifact, `ContextualWorkflow` for staged or recoverable work, and `ToolBackedWorkflow` when a deterministic router/gate owns fragile choices. `ShimSkill` contains only a canonical target and preset, and is allowed only when a newly accepted distribution contract explicitly ships that alias. `ReferenceSkill` contains knowledge without an invented workflow.

Use high freedom for safe implementation choices, medium for preferred patterns, and low only for fragile operations or invariant-sensitive ordering.

3. Place every rule once

Inventory current and proposed rules before editing. Record each rule's source, affected decision, frequency, and `RulePlacement`; then apply `placeRule`.

• Mechanizable safety and repeated transformations -> script, hook, or gate.
• Stage methods, templates, and examples -> stage reference.
• Project facts, ADRs, and learnings -> repository CodeStable artifacts.
• Every-invocation decisions and non-mechanizable hard gates -> harness.
• Generic advice, duplicated rationale, stale prose, and behavior-neutral steps -> remove.

Information must have one canonical home. Do not retain the same route, gate, or method in both the harness and a prose reference.

4. Build the context plan before the harness

Call `buildContextPlan` before writing the body. For every context source state when to load it, why it matters, how freshness is checked, when enough context has been gathered, and how an already loaded fact is reused.

Entry context i