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, +256 784 464178.

<!-- dual-compat-start -->
## 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.
<!-- dual-compat-end -->
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

```yaml
---
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:

- Runtime gate: keep the parsed description at or below 400 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:

```markdown
## 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:

```markdown
## 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` |
| Delivery Definition of Done | `references/delivery-definition-of-done.md` | `world-class-engineering` (closing gate for any meaningful change) |

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 |