| name | skill-composition-standards |
| description | Use when defining or reviewing how multiple skills compose through shared house style, input/output artifacts, evidence declarations, and reference boundaries; use skill-writing for one skill's authoring workflow and skill-taxonomy-and-routing for catalogue placement. |
| metadata | {"portable":true,"compatible_with":["claude-code","codex"]} |
Skill Composition Standards
Capability Contract
Composition review defaults to read-only. Editing skills, routers, templates, baselines, or CI requires explicit repository authority; publishing and deleting skills requires separate authority.
Degraded Mode
If validators, neighbouring skills, or templates are unavailable, return a contract gap report and mark routing or link checks unassessed. Do not declare conformance.
Decision Rules
| Choice | Action | Failure/risk avoided |
|---|
| Content is routing-critical | Keep it in the entrypoint | Hidden activation logic |
| Detail exceeds a focused pass | Extract to a linked reference | Overlong entrypoint |
| Neighbours overlap | Add positive and negative triggers | Routing collision |
Evidence Produced
| Category | Artifact | Acceptance condition |
|---|
| Correctness | Composition review record | Each applicable contract is passed or has a concrete finding. |
Worked Example
For a long schema catalogue, retain selection decisions and acceptance conditions in SKILL.md, extract the catalogue to references, link both directions, and rerun routing and link checks.
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.
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.
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.
Do Not Use When
- The task is unrelated to
skill-composition-standards or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.
Composition Prerequisites
- Gather relevant project context, constraints, and the concrete problem to solve; load
references only as needed.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.
Composition Entry Sequence
- Read this
SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.
Quality Standards
- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.
Early Composition Warnings
- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.
Initial Composition Artifacts
- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.
Core Reference Guidance
- 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
---
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 — Claude 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:
- Title —
# Skill Name (human-readable)
- Opening paragraph — one or two sentences stating the purpose
- Prerequisites — "Load X and Y first" when other skills must be loaded before this one
- When this skill applies — bullet list of 3–7 concrete scenarios
- Inputs — what artifacts this skill consumes from upstream (see Standard 2)
- Outputs — what artifacts this skill produces for downstream (see Standard 2)
- Non-negotiables — the hard rules this skill enforces (optional for non-engineering skills)
- Decision rules — at least one explicit decision table / ladder with thresholds
- Core content — the workflow, recipes, or patterns
- Anti-patterns — 5+ concrete "do not do this" items, each with the fix
- Read next — cross-references to adjacent skills
- References — list of
references/*.md deep-dive files
Rules:
- 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 Table Example
| 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 Table Example
| 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:
### No-Input Declaration Example
None. This skill is a foundational baseline.
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.
Contract gates (for review)
When reviewing a skill PR, verify:
- Does the skill's Outputs section declare the artifacts it produces?
- Does the skill's Inputs section declare what it consumes?
- Are the output artifact templates linked from
skill-composition-standards/references/?
- 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:
- Read the current SKILL.md and all references in one pass.
- Score against the 20-point checklist (
references/house-style-checklist.md). Note gaps.
- 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.
- Restructure the SKILL.md into the required section order. Keep all existing valuable content; just move it into the right sections.
- Extract depth into references — anything longer than a page of dense content moves to
references/<topic>.md.
- Add decision rules — if the skill currently describes "what to do" without "when one option wins over another", add a decision table.
- Add anti-patterns — concrete before/after examples for at least 5 mistakes.
- Add Read next — name 3–5 adjacent skills.
- Clean prose — no emojis, British English, language-tagged code fences.
- 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.
Composition Failure Catalogue
- 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.
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 checklistreferences/normalisation-playbook.md — how to upgrade a legacy skillreferences/baseline-contract-register.md — full artifact-contract register per baseline skill typereferences/context-map-template.mdreferences/adr-template.mdreferences/critical-flow-template.mdreferences/openapi-contract.mdreferences/error-model.mdreferences/threat-model-template.mdreferences/slo-template.mdreferences/release-plan-template.mdreferences/rollback-plan-template.mdreferences/runbook-template.mdreferences/test-plan-template.md
Workflow
- Discover the live skill and neighbours; stop if scope or ownership is unclear.
- Evaluate frontmatter, triggers, contracts, references, examples, and line count.
- Separate mechanical repairs from domain judgement and preserve substantive content.
- Run structural, link, and routing checks.
- Recover from failed gates by repairing the cited contract and rerunning the full set.
Inputs
| Input | Source/provider | If absent |
|---|
| Target skill, live neighbours, repository contract, and routing fixtures | Filesystem and maintainer | Stop conformance review and report the missing catalogue or contract. |
| Relevant templates, references, and validator output | Repository tools | Mark unavailable checks unassessed and do not declare conformance. |
Outputs
| Artifact | Consumer | Acceptance condition |
|---|
| Normalised skill contract | Maintainer and routing engine | Required sections, references, validation, and routing fixtures pass. |
Anti-Patterns
- Copying generic boilerplate. Fix: write domain decisions.
- Hiding routing logic in references. Fix: keep it in SKILL.md.
- Waiving findings in a baseline. Fix: clear the debt.
- Extracting content without a link. Fix: link both directions.
- Declaring success without tests. Fix: rerun structural and routing gates.
