skill-composition-standards

name	skill-composition-standards
description	Use when authoring, normalising, or reviewing skills that must follow the repository house style, capability boundaries, input/output contracts, decision rules, references, and composition gates.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

Skill Composition Standards

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Use when authoring a new skill, normalising an older skill, or reviewing a skill PR — defines the repository-wide house style (frontmatter, decision rules, anti-patterns, references), the output contracts each baseline-skill type must produce, and the input contracts each specialist skill must declare. This is the enforcement spine that makes the repository compose as a system, not a library of linked documents.

Do Not Use When

• A narrower neighbouring skill owns the task or this workflow would not change the result.

Required Inputs

• Use the task-specific inputs declared in the core workflow below; identify missing required inputs before acting.

Workflow

• Follow the ordered core workflow below and load only the references needed for the current branch.

Quality Standards

• Apply the domain gates, evidence requirements, and acceptance criteria defined below.

Anti-Patterns

• Do not replace the domain-specific rules below with generic advice or load unrelated references.

Outputs

• Produce the named artefacts and evidence specified by the core output contract below.

References

• Use the references/ directory for deep detail after reading the core workflow below.

The rules that make every skill in this repository compose cleanly with every other skill. Two concerns in one skill, because they are two faces of the same question: "what does this skill promise, and what is it allowed to expect?"

When this skill applies

• Creating a new skill — load this before skill-writing.
• Normalising an older skill against the current bar.
• Reviewing a skill PR for acceptance.
• Auditing the repository for drift.
• Introducing a new skill category (define its contract here first).

The two standards this skill codifies

Standard 1 — The house-style template (normalisation)

Every skill, old or new, must meet this shape. This is what "normalised" means.

Standard 2 — Input/Output contracts (composition)

Every skill must declare the artifacts it consumes (inputs) and the artifacts it produces (outputs). Downstream skills can then depend on those artifacts being present and well-formed.

---

Standard 1 — House-Style Template

Required frontmatter

The local boolean/list metadata contract is an engine extension, not proof of public interchange conformance or tested host support. Follow skill-writing for export boundaries and preserve additional declared runtime names.

---
name: <skill-slug>
description: Use when <trigger scenarios> — <what this skill covers>, <what it does not cover>. <One-line differentiator against neighbouring skills>.
---

Rules for description:

• Starts with "Use when" (trigger-phrasing — Codex loads skills on trigger match).
• Names the scenarios that should trigger loading.
• Names the neighbour skills (so the reader knows the difference).
• Single line, fits on screen without wrapping — under ~350 characters.

Required sections (in order)

A normalised SKILL.md must have these sections; each may be short, but none may be missing:

1. Title — # Skill Name (human-readable)
2. Opening paragraph — one or two sentences stating the purpose
3. Prerequisites — "Load X and Y first" when other skills must be loaded before this one
4. When this skill applies — bullet list of 3–7 concrete scenarios
5. Inputs — what artifacts this skill consumes from upstream (see Standard 2)
6. Outputs — what artifacts this skill produces for downstream (see Standard 2)
7. Non-negotiables — the hard rules this skill enforces (optional for non-engineering skills)
8. Decision rules — at least one explicit decision table / ladder with thresholds
9. Core content — the workflow, recipes, or patterns
10. Anti-patterns — 5+ concrete "do not do this" items, each with the fix
11. Read next — cross-references to adjacent skills
12. References — list of references/*.md deep-dive files

Rules:

• Repository gate: keep the parsed description at or below 350 characters; the aggregate runtime budget is checked separately.

• Discovery metadata contains triggers and boundaries, not procedures, examples, or full policy text.

• SKILL.md ≤ 500 lines. Overflow goes into references/.

• Every code snippet has a language tag on the fence.

• No emojis unless the user explicitly requests them.

• British English.

• Imperative voice for rules. Declarative for explanations.

Required depth structure

• Anything deeper than a single reading pass must be extracted to references/<topic>.md.
• Each reference file 150–400 lines.
• Reference files follow the same no-emoji / British-English / language-tagged-fences rules.

Required cross-linking

• The SKILL.md "Read next" section names adjacent skills.
• Every reference file links back to its parent SKILL.md at the top.
• Every skill declares its neighbour-differentiator in the description.

See references/house-style-checklist.md for the full 20-point checklist and references/normalisation-playbook.md for how to bring a legacy skill up to this bar.

---

Standard 2 — Input/Output Contracts

The principle

Every skill declares what it produces (outputs) and what it consumes (inputs). Downstream skills can then depend on those artifacts being present and well-formed. The baseline skills produce the artifact set that specialist skills consume, and specialist skills produce narrower deliverables that platform skills consume.

Beyond Inputs and Outputs, specialist skills also declare which of seven fixed validation categories their artifacts contribute to. That third contract lives in validation-contract; it turns scattered validation skills into a coherent ship-readiness check and produces the canonical Release Evidence Bundle at release time.

Required contract declaration

Every SKILL.md has an Inputs and an Outputs section with a table:

## Inputs

| Artifact | Produced by | Required? | Why |
|---|---|---|---|
| Context map | `system-architecture-design` | required | service/module boundaries |
| Access pattern list | `database-design-engineering` | required | shapes the API contract |
| Threat model | `vibe-security-skill` | optional | informs auth rules |

## Outputs

| Artifact | Consumed by | Template |
|---|---|---|
| OpenAPI 3 spec | frontend, mobile, SDK skills | `skill-composition-standards/references/openapi-contract.md` |
| Error model | frontend, mobile | `skill-composition-standards/references/error-model.md` |
| Idempotency map | `reliability-engineering` | inline |

If a skill does not depend on any upstream artifact, its Inputs section says so:

## Inputs

None. This skill is a foundational baseline.

Every skill that expects runner capabilities must also declare the minimum capability contract in its workflow or non-negotiables. Express it by capability (read, search, edit, execute, network, delegate) and define safe fallback behaviour when an optional capability is absent. Keep vendor tool names and model settings in adapters. Analysis and review default to read-only; mutation requires the task to authorise it.

Role definitions are not interchangeable with skills. A role describes the specialised worker, permission boundary, and handoff; a skill describes a reusable procedure. Keep them separate when either can be reused independently.

Standard artifact types

The repository defines these standard artifacts. Each has a template in references/.

Artifact	Template file	Produced by (typical)
Context map	references/context-map-template.md	system-architecture-design
ADR set	references/adr-template.md	any skill making a structural decision
Critical-flow table	references/critical-flow-template.md	system-architecture-design
Entity model	references/entity-model-template.md	database-design-engineering
Access-pattern list	references/access-patterns-template.md	database-design-engineering
Migration plan	references/migration-plan-template.md	database-design-engineering, deployment-release-engineering
OpenAPI contract	references/openapi-contract.md	api-design-first
Error model	references/error-model.md	api-design-first
Threat model	references/threat-model-template.md	vibe-security-skill
SLOs + alert plan	references/slo-template.md	observability-monitoring
Release plan	references/release-plan-template.md	deployment-release-engineering
Rollback plan	references/rollback-plan-template.md	deployment-release-engineering
Runbook	references/runbook-template.md	reliability-engineering, observability-monitoring
Test plan + evidence	references/test-plan-template.md	advanced-testing-strategy

A skill that produces one of these artifacts must produce it in the format the template specifies. Downstream skills consume the template-format version.

The Delivery Definition of Done is the terminal artifact: it bundles the release-time outputs (tests, release plan, rollback plan, runbook, SLOs, maintenance notes) into one checkable handoff so the work can be operated and maintained by a team that did not write it. Meaningful changes are not "done" until that pack is whole.

Contract gates (for review)

When reviewing a skill PR, verify:

1. Does the skill's Outputs section declare the artifacts it produces?
2. Does the skill's Inputs section declare what it consumes?
3. Are the output artifact templates linked from skill-composition-standards/references/?
4. Does the skill produce the artifact in the template format, not a free-form substitute?

If any answer is no, the PR fails the contract gate.

---

Baseline output contracts (per baseline skill type)

Each baseline skill type has a mandatory output set. These are the contracts specialist skills depend on.

world-class-engineering

Outputs: release gate checklist, production-readiness rubric.

system-architecture-design

Outputs: context map + critical-flow table + ADR set + dependency diagram notes + failure mode list.

database-design-engineering

Outputs: entity model + access-pattern list + index plan + migration plan + retention + tenancy notes.

api-design-first

Outputs: OpenAPI contract + auth model + error model + idempotency keys + observability notes.

observability-monitoring

Outputs: SLOs + alert rules + dashboards + runbook-per-service.

reliability-engineering

Outputs: retry/timeout matrix + degradation plan + incident playbook + postmortem template.

deployment-release-engineering

Outputs: release plan + rollback plan + migration choreography + post-deploy verification steps.

advanced-testing-strategy

Outputs: test plan + test evidence bundle + risk-based coverage map.

vibe-security-skill

Outputs: threat model + abuse case list + auth/authz matrix + secret handling plan.

See references/baseline-contract-register.md for the full list and full schemas.

---

Normalisation workflow (bringing older skills up)

When normalising an older skill:

1. Read the current SKILL.md and all references in one pass.
2. Score against the 20-point checklist (references/house-style-checklist.md). Note gaps.
3. Declare contracts first — write the Inputs and Outputs sections. If the skill currently produces free-form output, decide what artifact type(s) it should produce and point at the templates.
4. Restructure the SKILL.md into the required section order. Keep all existing valuable content; just move it into the right sections.
5. Extract depth into references — anything longer than a page of dense content moves to references/<topic>.md.
6. Add decision rules — if the skill currently describes "what to do" without "when one option wins over another", add a decision table.
7. Add anti-patterns — concrete before/after examples for at least 5 mistakes.
8. Add Read next — name 3–5 adjacent skills.
9. Clean prose — no emojis, British English, language-tagged code fences.
10. Run validator — python -X utf8 skill-writing/scripts/quick_validate.py <skill>.

See references/normalisation-playbook.md for the full procedure with examples.

---

Enforcement

This skill is advisory in mechanism, mandatory in convention. There is no CI bot (yet) that blocks a skill from merging if it fails the contract gate. Enforcement is by:

• Referencing this skill from world-class-engineering (repo-wide baseline).
• Referencing this skill from skill-writing (skill-authoring guide).
• Using the 20-point checklist in review.
• Running quick_validate.py in CI.
• Running the normalisation playbook on one older skill per week until the repository is normalised.

Future work: a CI hook that parses Inputs / Outputs tables and warns when a claimed upstream artifact is not declared by any upstream skill.

The runtime metadata validator is now the required cross-engine gate. Run the coordination engine's validator against the exact roots exposed by the host, including deliberately enabled plugin skill roots. Keep the runtime set below the entry-count and aggregate metadata limits; a per-repository pass does not prove that the assembled catalog fits.

Anti-patterns

• A skill with no Outputs declaration (every skill produces something).
• A skill that claims an input that no upstream skill produces — the input does not actually exist.
• Output described in prose rather than pointing at a template — loses composability.
• "References" section that is just a list of bullet points without the files existing.
• Decision rules written as prose paragraphs instead of tables / ladders.
• Anti-patterns section that lists principles ("avoid tight coupling") rather than concrete before/after examples.
• Neighbour skill not mentioned anywhere, leaving overlap ambiguous.
• Skill over 500 lines with no references/ directory.
• Canonical instructions coupled to one runner's command names, model names, or directory conventions.
• A role persona presented as a skill without a repeatable procedure and output contract.
• An adapter that duplicates the canonical instruction body and can drift from it.

Read next

• skill-writing — authoring process, validator, frontmatter rules.
• world-class-engineering — repository-wide quality bar that references this skill.
• advanced-testing-strategy, observability-monitoring, reliability-engineering, deployment-release-engineering — the operability baseline skills whose contracts anchor the repository.

References

• references/house-style-checklist.md — 20-point review checklist
• references/normalisation-playbook.md — how to upgrade a legacy skill
• references/baseline-contract-register.md — full artifact-contract register per baseline skill type
• references/context-map-template.md
• references/adr-template.md
• references/critical-flow-template.md
• references/openapi-contract.md
• references/error-model.md
• references/threat-model-template.md
• references/slo-template.md
• references/release-plan-template.md
• references/rollback-plan-template.md
• references/runbook-template.md
• references/test-plan-template.md

Capability contract

Read and search are required. Editing is allowed only for an authorised normalisation task. Execution is limited to repository validators; network access and delegation are optional.

Degraded mode

Without editing or execution, return a scored gap list and exact proposed changes. Never claim compliance without validator evidence.

Decision rules

Condition	Action	Wrong-choice failure
Existing scope is sound	Normalise in place	Unnecessary split fragments routing
Two independent triggers or outputs exist	Split after collision analysis	One oversized skill loads irrelevant context
Neighbour owns the same trigger and contract	Merge or alias	Duplicate routes compete indefinitely