Skip to content
sdlc

Skill shape — required SKILL.md structure and post-execution assessment

Status: open/proposed

The required shape of a skill in SDLC: what every SKILL.md must include, including a post-execution assessment as a standard step.

Summary

Section titled “Summary”
  • Pending — exploratory ADR; outcomes populate here when it reaches open/accepted.
  • Proposes a workflow contract for every SKILL.md: required body sections (Trigger / Project context / Steps / Outputs / Post-execution assessment / Failure modes).
  • Load-bearing piece: a required post-execution assessment step so skill behavior compounds into improvement instead of evaporating per run.

Decision

Section titled “Decision”

(Proposed, not yet accepted.) Every skill is a workflow contract with a declared shape and a required closing post-execution assessment. A scoped Standard (S<id>-skill-shape) is expected to be extracted from the load-bearing pieces — particularly the post-execution-assessment contract — once the design hardens. The full proposal is in the sections below.

What this is

Section titled “What this is”

Skills under plugin/skills/<slug>/SKILL.md are the LLM-orchestrated workflows that drive SDLC today. They are the system’s highest-leverage artifact and currently the least-rigorous one: each SKILL.md sets its own shape. House conventions exist (see references) but no contract says what every skill must include.

This ADR proposes that contract. The most opinionated piece: every skill ends with a post-execution assessment step that captures what just happened, what surprised the runner, and what follow-ups should land, so skill behavior compounds into improvement instead of evaporating after each invocation.

Core ideas

Section titled “Core ideas”
  • A skill is a workflow contract, not free-form prose. Even as markdown, every SKILL.md has a shape: trigger, steps, exits. Making the shape explicit lets skills be evaluated, refactored, and (eventually) generated against a contract.
  • Skills are LLM heads. The deterministic-tail / LLM-head split from S-0004-sdlc-cli-llm-head-deterministic-tail applies: where a deterministic verb exists, the skill invokes it and trusts the output. Where one doesn’t, the skill’s prose IS the implementation, and that’s the part most worth hardening over time.
  • Every skill declares its extension points. When it can be invoked, what it accepts, what it produces, what side effects it has. This makes skills composable: a parent skill can dispatch a child skill without re-reading its prose.
  • Post-execution assessment is a required final step. After the work completes (or is interrupted/abandoned), the skill performs a structured assessment. This is the load-bearing piece of this ADR: without it, skills stay opaque and improvement is anecdotal.

Required shape

Section titled “Required shape”

Frontmatter (already convention today):

  • description: |: one paragraph, third person, packing BOTH what the skill does AND when to trigger it (key terms/contexts), since it is the single most important field for skill selection. Authoring rules: S-0006-skill-md-is-direct-instruction rule 4.
  • allowed-tools:: the explicit tool list.
  • Optional: model:, argument-hint:.

S-0006-skill-md-is-direct-instruction carries the full skill-authoring rule set — phrasing discipline plus the structural/equipping rules: description/triggering, degrees-of-freedom-match-fragility, decomposition + verification step, progressive disclosure, formatting/placement, examples, eval — with an evidence base. Where this ADR and S-0006 overlap, S-0006 governs. This ADR’s contributions, which S-0006 does not settle, are the required body-section contract and the post-execution-assessment step.

Body sections (proposed minimum, in order):

  1. Trigger. When this skill should run. Slash-command invocation shape and any argument shape.
  2. Project context. What the skill assumes about the project on disk. Read once; don’t re-derive every run.
  3. Steps. The actual workflow, numbered, each step concrete and actionable.
  4. Outputs / postconditions. What’s left behind on disk, what structured marker (if any) is printed to stdout.
  5. Post-execution assessment. See below.
  6. Failure modes. What to do when steps fail; what the skill does NOT recover from on its own.

Progressive disclosure

Section titled “Progressive disclosure”

A SKILL.md is primarily a workflow statement, not a tutorial. The body should minimize prose about reasoning, sub-function behavior, or “why we chose this approach”; that content belongs in an ADR, a Standard, or a per-skill doc, not in the executable contract. (This is the progressive-disclosure practice codified with an evidence base in S-0006-skill-md-is-direct-instruction.)

Steps lead with the happy path. Failure states, edge cases, and “the reason this step exists” are referenced out (to a per-skill doc, the underlying script’s docstring, a Standard, or the closing post-execution-assessment loop) rather than inlined. A reader following the happy path should not have to wade through failure prose to find the next instruction.

Concretely:

  • Happy path inline; failure paths referenced. Each step states what to do when it works; failure handling lives in the Failure Modes section or in linked references.
  • Sub-function behavior is not the skill’s job. If a step calls a script, the skill describes that the script runs and what the skill does with the output, not how the script works.
  • Reasoning lives upstream. Why this skill exists, why the steps are shaped this way, what alternatives were considered: ADR / Standard territory. Reference, don’t restate.
  • Repetition is the failure mode. When a skill duplicates guidance that lives in a Standard or an upstream reference, drift is inevitable. Cite the upstream instead.

This rule is the skill-authoring corollary of P-0005-schema-over-prose (model what can be modeled) and P-0001-prefer-deterministic-over-llm (let the deterministic tail carry mechanical detail; the LLM-driven skill stays high-level).

Post-execution assessment

Section titled “Post-execution assessment”

After the main work completes (successfully, partially, or with the user abandoning mid-flow) every skill captures a structured assessment covering at least:

  • Goal achievement. Did the skill accomplish what it was invoked to do? yes / no / partial, with one-line reason.
  • Surprises. Anything the skill discovered that the SKILL.md didn’t anticipate. Examples: a file already had the change; the user’s actual intent was different than the trigger read; a side effect surfaced; a tool returned an unexpected shape.
  • Follow-ups. Concrete bullets for sdlc backlog create or task creation. The skill must NOT silently swallow follow-ups; capturing them is the assessment’s job.
  • Skill self-critique. Anything in the skill’s own shape that made the work harder than it should have been: ambiguous step, missing branch, brittle assumption, redundant prompt. Captured for later skill refinement.

The assessment is structured (not free-form prose) so it can be aggregated across runs to surface patterns. The exact storage shape is open; see Open questions.

Extension points

Section titled “Extension points”

Applying the definition-surface reasoning of S-0005-entity-definition-contract (skills are not entities in its strict sense), every skill declares:

  • Invocation surfaces. From a Claude session (the primary today), as a sub-agent dispatch (skill-as-tool), from a parent skill chain, potentially from a CLI invocation. Each surface has different context assumptions and the skill should declare which it supports.
  • Hooks. Pre-execution validation, post-execution assessment (above), failure-mode handlers, abandonment cleanup.
  • Inputs. Skill arguments, ambient session state, project state on disk, environment.
  • Outputs. Side effects on the working tree, structured stdout markers, follow-up captures, assessment artifact.

Open questions

Section titled “Open questions”
  • Where does the assessment artifact land? Options: stdout for the current session only (ephemeral); a file under .sdlc/skill-runs/<skill>/<timestamp>.md; appended to a per-skill log; structured frontmatter in a dedicated assessment artifact; routed into the backlog-capture flow when follow-ups are present. Multiple may apply at different layers (session stdout for the user; aggregated artifact for cross-run analysis).
  • Is the assessment an LLM step or a deterministic-tail step? Hybrid likely: the qualitative parts (surprises, self-critique) are LLM-shaped; the structural parts (timing, tool-call count, exit code, files touched) are deterministic and can be captured by a wrapper.
  • Should /assess <skill> exist as an independent verb that re-runs the assessment over a recent session’s transcript, for cases where the original run was interrupted before assessment?
  • Relationship to the existing per-skill test harness (the plugin/skills/<slug>/tests/*.test.ts pattern, e.g. run_evals.test.ts). The harness measures skill behavior externally with fixtures; the assessment is the skill’s own retrospective in production. They may converge into one feedback loop, or stay separate by design.
  • How does the assessment feed Continuous Improvement? vision has workflows maturing from prose skills to deterministic tails as their happy paths stabilize. This ADR’s assessment is the per-run capture that would ground that maturation; how runs aggregate is a downstream design.
  • Granularity of the contract. Should the assessment requirement apply uniformly to every skill, or be opt-out for trivial ones (e.g. a skill that’s purely a thin dispatcher)? Lean toward uniform: even thin dispatchers benefit from “did the call I dispatched succeed?”.

References

Section titled “References”

← Back to Decisions