Introduce super-skill composition; refactor al-code-review into super + two leaves

DO contract (skills/do.md)
- New 'sub-skills' optional frontmatter field on action skills: when
  present and non-empty, the skill is a super-skill that composes
  other action skills.
- New 'Composition (super-skills)' section covering section
  interpretation, outcome rollup, summary aggregation, and suppression
  scope.
- Output schema gains three optional fields: 'from-sub-skill' on each
  finding, top-level 'sub-results[]' carrying nested findings-reports,
  and top-level 'skipped-sub-skills[]'.
- Super-skills MUST NOT filter sub-skills by task content; leaves own
  task-level applicability and signal via outcome.
- Findings from a failed sub-skill MUST NOT flow into the parent's
  findings[] or counts, consistent with DO's rule that consumers
  ignore a failed skill's findings. Reports are still preserved in
  sub-results[] for traceability.
- Rolled-up non-citation finding ids MUST be prefixed with the sub-
  skill id to prevent collisions across sub-skills. Citation-based
  ids are already unique via repo path and are not rewritten.
- Outcome rollup rules updated: 'partial' covers S = {partial},
  {partial, partial}, and {partial, failed}. Empty worklist rolls up
  to 'not-applicable' with outcome-reason.
- Nested super-skills are not permitted in v1.

Reference skills (microsoft/skills/)
- al-code-review.md rewritten as the canonical super-skill: lists
  al-performance-review and al-security-review as sub-skills, orch-
  estrates invocation, aggregates output, and includes a worked
  rolled-up JSON example plus the empty-corpus rollup.
- al-performance-review.md added as a leaf reference skill for the
  performance knowledge domain.
- al-security-review.md added as a leaf reference skill for the
  security knowledge domain.
- Both leaves retain the leaf-level rules validated in the prior
  pass: partial-context message requirement, worklist-scoped
  suppression, application-area semantics, and the platform-guarantee
  threshold for blocker severity.

README updated to describe leaf vs super-skill and link all three
reference skills.

Two rubber-duck passes tightened the contract and caught schema
violations in the worked examples before commit.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-04-17 13:06:03 +02:00
parent 7ad0c03c4d
commit 5aaa58e8ee
5 changed files with 470 additions and 57 deletions

View file

@ -36,7 +36,7 @@ Skills define how agents consume knowledge. They come in two flavors:
Schema + Use and New Knowledge are deliberately separate: one is the reader's contract, the other is the writer's guide. New Knowledge depends on Schema + Use but does not duplicate it.
- **Action skills** — concrete skills that follow the Action Skill template to do real work (review code, audit telemetry, etc.). Action skills live inside the layers that own them (`/microsoft/skills/`, `/community/skills/`). The canonical reference implementation is [`microsoft/skills/al-code-review.md`](microsoft/skills/al-code-review.md) — skill authors should use it as a starting point.
- **Action skills** — concrete skills that follow the Action Skill template to do real work (review code, audit telemetry, etc.). Action skills live inside the layers that own them (`/microsoft/skills/`, `/community/skills/`). An action skill is either a **leaf** that evaluates knowledge files directly, or a **super-skill** that composes other action skills (declared via `sub-skills` in frontmatter). The canonical reference is [`microsoft/skills/al-code-review.md`](microsoft/skills/al-code-review.md) (super-skill), which composes [`microsoft/skills/al-performance-review.md`](microsoft/skills/al-performance-review.md) and [`microsoft/skills/al-security-review.md`](microsoft/skills/al-security-review.md) (leaves).
### Agent bootstrapping