Skip to content

ADR-0021: Skill Files Are Executable Prompt Logic Subject to the ADR Gate

Status: Accepted Deciders: elcubonegro, Claude (Sonnet 4.6) Date: 2026-03-27

Context and Problem Statement

Cornerstone's .agents/skills/**/*.md files are not passive documentation. They are executable prompt logic: protocols with conditionals, output contracts, failure modes, and routing rules that directly determine agent behaviour on every session. Changing a SKILL.md is behaviourally equivalent to changing a function — it alters what the system does.

Despite this, skill file changes have been treated as docs commits: no semver bump, no ADR requirement, no CI gate. This creates three concrete risks:

  1. Silent regression — a skill change committed as docs produces no version signal and no ADR trail. No one knows when behaviour changed or why.
  2. No authoring standard — contributors write skills in inconsistent styles because there is no enforced contract for what a skill file must contain.
  3. Broken routing undetected — AGENTS.md and SKILL.md files reference each other by file path. A renamed or deleted skill breaks routing with no CI signal.

Decision Drivers

  • Skill files are consumed as prompts; their quality directly determines agent output quality.
  • The ADR gate already enforces the "decision before code" principle for library source — the same principle applies to prompt logic.
  • Semver must reflect behavioural changes. A skill edit that changes agent behaviour is a fix or feat, not a docs.
  • The architect review identified this as the highest-severity finding in the docs-as-prompts analysis.

Considered Options

  • Option A: Treat skills as documentation — no gate, no bump. Status quo.
  • Option B: Gate skill changes with the ADR gate; introduce a skill commit type for semver.
  • Option C: Create a separate skill-review CI job distinct from the ADR gate.

Decision Outcome

Chosen option: Option B.

Rationale: - Option A is the demonstrated failure mode — it has already produced undocumented skill changes with no audit trail. - Option C adds a second gate system to maintain alongside the ADR gate, violating the deduplication mandate. The ADR gate is the right layer; extend it. - Option B reuses the existing check_adr_gate.py infrastructure and produces a consistent authoring contract: "any behavioural change — whether to source code or to prompt logic — requires an ADR."

What changes

1. ADR gate extended to guard skill files

GUARDED_PATTERNS in check_adr_gate.py gains two new patterns:

".agents/skills/**/*.md",
".agents/skills/*.md",

Scope: - Generated projects ({{cookiecutter.project_slug}}/tools/check_adr_gate.py): guards .agents/skills/ within the generated project. - Cornerstone root: the same template file is the canonical implementation. Cornerstone's own CI inherits the guard when it runs the gate against its own diff.

2. skill commit type → PATCH semver bump

tools/bump_version.py gains "skill": "patch" in BUMP_MAP.

A skill(version-manager): fix output contract commit now produces a PATCH bump, making the version history a faithful record of behavioural changes.

3. Authoring contract (enforced by ADR requirement, not tooling)

Every skill file that modifies agent behaviour must be accompanied by either: - A new ADR (for decisions that have not been recorded), or - A reference to an existing ADR in the skill's frontmatter (adr: ADR-NNNN), indicating the change is an implementation update of an already-accepted decision.

The second case uses [skip-adr] in the commit message with the referenced ADR number noted in the message body.

Bypass

[skip-adr] applies to skill changes the same way it applies to library changes. Appropriate uses: - Typo / formatting fix in a skill file with no behavioural effect - Sync of a skill file already covered by an existing ADR ([skip-adr] covered by ADR-0009)

Scope

Cornerstone is a framework, not an application. The generation boundary is hard:

Cornerstone source (framework)         ← ADR gate governs this
├── .agents/skills/
├── {{cookiecutter.project_slug}}/     ← template scaffold only; source, not runtime
└── builder/{{cookiecutter.project_slug}}/

──────────── generation boundary ────────────

Generated project (customer runtime)   ← outside Cornerstone's jurisdiction
Context Gate applies? Rationale
Cornerstone root .agents/skills/ Yes Primary skill authoring location
{{cookiecutter.project_slug}}/.agents/skills/ Yes Template source — baked into the scaffold, governed by Cornerstone
builder/{{cookiecutter.project_slug}}/.agents/skills/ Yes Same — builder scaffold source
Generated project at runtime No Customer territory; Cornerstone ships the gate as a tool but does not govern how customers use their own skill files

The gate ships into generated projects as a default tool. Whether the customer team enforces it on their own skill edits is their architectural decision, not Cornerstone's.

Positive Consequences

  • Every skill change has an audit trail (ADR or [skip-adr] with justification).
  • Semver accurately reflects behavioural changes to prompt logic.
  • The skill commit type in git log makes archaeology of agent behaviour changes trivial.

Negative Consequences

  • Minor friction for trivial skill edits (use [skip-adr]).
  • The gate cannot verify semantic quality of a skill, only that an ADR exists. Authoring quality remains a human review concern.
  • Related: ADR-0014 (atomic commit policy)
  • Related: ADR-0020 (agentic semantic versioning)
  • Related: ADR-0007 (OWASP CI/CD — the gate infrastructure)
  • Implementation: {{cookiecutter.project_slug}}/tools/check_adr_gate.py, tools/bump_version.py