Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 09:26:52 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Introduce the entry-point skill (skills/entry.md)

Browse source 
Add a new skill kind, 'entry-point', and its sole instance at
skills/entry.md. When an orchestrator points an agent at BCQuality,
the agent's first call is Entry: it receives a task context and
returns a dispatch record naming the action skill(s) to invoke.
Routing logic lives in Entry, not in the orchestrator.

Entry structurally follows DO's Source -> Relevance -> Worklist ->
Action pattern but the units it selects are action skills (not
knowledge files) and its output is a dispatch record (not a
findings-report).

Contract highlights:
- Inputs semantics in DO clarified as any-of: orchestrator supplies
  whichever listed input types it has; skill must return
  'not-applicable' if the subset is insufficient. This matches
  the existing al-* canonical skills which declare
  [pr-diff, file-path] as alternatives.
- Relevance admits candidates whose inputs intersect
  inputs-available, not whose inputs are a subset.
- Dispatched inputs are the intersection, not the full
  inputs-available set, to avoid leakage between skills.
- Super-skill precedence in Worklist supersedes a sub-skill only
  when the goal is a broader match for the super than the sub.
  When the goal specifically names a concern the sub handles
  (e.g., 'performance review'), the sub wins and the super is
  dropped with reason 'narrower-sub-skill-selected'.
- Skill layer precedence is defined here as custom > community >
  microsoft, matching READ's rule for knowledge files.
- skipped[] carries 'superseded-by' for layer-precedence,
  sub-skill, and super-skill drops, for traceability.

Propagate the concept through:
- skills/README.md: distinguish the runtime entry-point skill from
  the three meta-skill contracts.
- skills/do.md: acknowledge entry-point alongside meta-skills as
  the only kinds that live outside a layer.
- README.md: rewrite the Skills and Agent bootstrapping sections
  so the bootstrap instruction is 'invoke /skills/entry.md first'.
- agent-consumption.md: update the Mermaid flow and step narrative
  to show Entry dispatch, with READ and DO read on demand.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-04-17 14:01:09 +02:00
parent 94ec5d7da0
commit aa243a93ec
5 changed files with 215 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -27,20 +27,22 @@ All three layers are enabled by default when an agent consumes BCQuality. Conten
### Skills
Skills define how agents consume knowledge. They come in two flavors:
Skills define how agents consume knowledge. They come in three flavors:
- **Meta-skills** (`/skills/`) — the three globally shared skills that bootstrap every interaction with BCQuality:
1. **Schema + Use** (READ, [`skills/read.md`](skills/read.md)) — how to read a knowledge file: interpret frontmatter, parse sections, understand layer precedence. This is the consumer's reference — any agent or skill that reads knowledge files depends on it.
2. **Action Skill** (DO, [`skills/do.md`](skills/do.md)) — the template every action skill follows. Defines the four-step pattern (Source → Relevance → Worklist → Action) and the structured output format that orchestrators expect. This is the skill author's reference.
3. **New Knowledge** (WRITE, [`skills/write.md`](skills/write.md)) — how to author a valid knowledge file. References Schema + Use for the format specification and adds authoring rules (atomicity, section guidance). This is the contributor's reference.
- **The entry-point skill** ([`skills/entry.md`](skills/entry.md)) — the first skill an agent invokes at runtime. Given a task context (goal, available inputs, technologies, BC version, etc.), it returns a **dispatch record** naming the action skill or skills to invoke next. Routing logic lives here, not in the orchestrator.
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.
- **Meta-skill contracts** (`/skills/`) — three stable references that define the rest of the repo:
1. **Schema + Use** (READ, [`skills/read.md`](skills/read.md)) — how to read a knowledge file: interpret frontmatter, parse sections, understand layer precedence. Any agent or skill that reads knowledge files depends on it.
2. **Action Skill** (DO, [`skills/do.md`](skills/do.md)) — the template every action skill follows. Defines the four-step pattern (Source → Relevance → Worklist → Action) and the structured output format that orchestrators expect.
3. **New Knowledge** (WRITE, [`skills/write.md`](skills/write.md)) — how to author a valid knowledge file. References Schema + Use for the format specification and adds authoring rules (atomicity, section guidance).
- **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).
READ and DO are read on demand — typically when the first dispatched action skill runs. They are not prerequisites for invoking Entry. WRITE is only used when scaffolding new content.
- **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/`, `/custom/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
Agents discover BCQuality through `/skills/`. An orchestrator (such as AL-Go) points the agent at the repository, and the agent reads the meta-skills in `/skills/` first to learn how to interpret knowledge files, follow the action-skill pattern, and produce output the orchestrator can consume. The meta-skills are the entry point — no prior knowledge of BCQuality's structure is required.
An orchestrator (such as AL-Go) points the agent at BCQuality's URL and provides a task context. The agent's first call is `/skills/entry.md`, which returns a dispatch record naming the action skill(s) to invoke. The agent then invokes each dispatched skill in turn, reading READ and DO on demand. No prior knowledge of BCQuality's structure is baked into the orchestrator — only the convention *"invoke `/skills/entry.md` first."*
## Knowledge file format
@ -103,7 +105,7 @@ For the end-to-end flow — from orchestrator trigger through to how output reac
## Repository structure
```
├── /skills/ # Global meta-skills (Schema+Use, Action Skill, New Knowledge)
├── /skills/ # Global: entry-point skill + meta-skill contracts (READ, DO, WRITE)
├── /.github/ # Actions and workflows
├── /microsoft/ # Microsoft-endorsed layer
│ ├── /knowledge/ # Knowledge files by domain

46
agent-consumption.md
View file

@ -9,37 +9,35 @@ For the high-level framing and repo structure, start with the [README](README.md
- **Orchestrator** — the tool that triggers work (e.g. AL-Go on a pull request, or a VS Code extension on save). Lives *outside* BCQuality. Knows *when* to run something, not *what* to run.
- **Agent** — an LLM-driven process spawned by the orchestrator. The agent has no built-in knowledge of BC or of BCQuality's conventions. It knows how to read instructions and call tools.
- **BCQuality repo** — two kinds of content:
- **Meta-skills** in `/skills/` — the READ · DO · WRITE contracts that teach an agent how to work with the repo.
- **Layer content** in `/microsoft/` and `/community/` — knowledge files and action skills grouped by authority.
- **Global skills** in `/skills/` — the `entry.md` entry-point skill plus the READ · DO · WRITE contracts that govern the rest of the repo.
- **Layer content** in `/microsoft/`, `/community/`, and `/custom/` — knowledge files and action skills grouped by authority.
## The flow
```mermaid
flowchart LR
O[Orchestrator<br/>AL-Go] -->|1 trigger| A[Agent]
A -->|2 read /skills/| M[Meta-skills<br/>READ · DO · WRITE]
M -->|3 pick skill| S[Action skill<br/>e.g. al-code-review]
S -->|4 execute| P[Source → Relevance<br/>→ Worklist → Action]
P -->|5 emit| R[Findings · References<br/>· Confidence]
R -->|6 integrate| O
O[Orchestrator<br/>AL-Go] -->|1 trigger + task context| A[Agent]
A -->|2 invoke entry.md| E[Entry<br/>routing skill]
E -->|3 dispatch record| A
A -->|4 invoke dispatched skill| S[Action skill<br/>e.g. al-code-review]
S -->|5 execute| P[Source → Relevance<br/>→ Worklist → Action<br/>reading READ · DO on demand]
P -->|6 emit| R[Findings · References<br/>· Confidence]
R -->|7 integrate| O
```
### 1. Orchestrator triggers
The orchestrator has a URL setting that points at BCQuality (default: `github.com/microsoft/BCQuality`) and a task to perform. It hands the task to an agent and says: *your source of truth lives at that URL; start by reading `/skills/`*.
The orchestrator has a URL setting that points at BCQuality (default: `github.com/microsoft/BCQuality`) and a task to perform. It hands the agent a **task context** — goal, inputs available (`pr-diff`, `file-path`, …), technologies, BC version, enabled layers — and says: *your source of truth lives at that URL; start by invoking `/skills/entry.md`*.
### 2. Agent bootstraps on meta-skills
The agent has no prior knowledge of BCQuality's conventions. It reads `/skills/` first:
### 2. Agent invokes Entry
The agent reads `/skills/entry.md` and runs it against the task context. Entry applies its Source → Relevance → Worklist → Action steps over the action skills under `*/skills/**/*.md` and returns a **dispatch record**: the set of action skills to invoke, plus a list of candidates it skipped (with reasons). Routing is a skill, not orchestrator logic.
- **READ** (Schema + Use) — how to interpret a knowledge file: frontmatter fields, section semantics, layer precedence. Any skill that consumes knowledge depends on this.
- **DO** (Action Skill) — the template every action skill follows. Defines the four-step pattern and the structured output format.
- **WRITE** (New Knowledge) — authoring rules. Not used during consumption; used when contributors or agents scaffold new knowledge.
### 3. Agent consumes the dispatch record
The dispatch record names one or more action skills and the subset of inputs each should receive. If the outcome is `no-match` or `failed`, the agent returns the record to the orchestrator unchanged.
After this step, the agent is fluent in BCQuality without anything hardcoded in the orchestrator.
### 4. Agent invokes each dispatched action skill
Action skills live inside the layers — `/microsoft/skills/`, `/community/skills/`, `/custom/skills/` — so their authority is carried by their location. For a PR review, Entry typically dispatches `microsoft/skills/al-code-review.md`. The agent reads the file and executes it.
### 3. Agent selects an action skill
Action skills live inside the layers — `/microsoft/skills/` and `/community/skills/` — so their authority is carried by their location. For a PR review, the agent finds a review-type skill (for example `microsoft/skills/al-code-review.md`) and loads it.
### 4. Action skill executes the four-step pattern
### 5. Action skill executes the four-step pattern
Each action skill is a markdown file that specifies what to do at each step. The template is always the same:
@ -52,7 +50,9 @@ Each action skill is a markdown file that specifies what to do at each step. The
Example: a performance review skill sources from `/microsoft/knowledge/performance/` and `/community/knowledge/performance/`, filters to `bc-version: 26` and `technologies: [al]`, narrows the 25 candidate files to the 8 that apply to the 15 objects changed in the PR, and then evaluates each file against the diff.
### 5. Agent emits structured output
At this point the agent reads READ and DO on demand — it needs READ to interpret each knowledge file's frontmatter and sections, and DO to shape its output. Those contracts are fetched when first needed, not as part of bootstrap.
### 6. Agent emits structured output
The output contract is defined in the DO meta-skill so that every action skill — today's and next year's — produces the same shape:
- **Outcome** — `completed`, `not-applicable`, `no-knowledge`, `partial`, or `failed`. An orchestrator can distinguish a clean run from a no-op from a failure without guessing.
@ -63,15 +63,15 @@ The output contract is defined in the DO meta-skill so that every action skill
The orchestrator parses this **without skill-specific logic**. This is the point of the contract: orchestrators and action skills evolve independently.
### 6. Orchestrator integrates
### 7. Orchestrator integrates
The orchestrator turns findings into PR comments, build gates, or IDE diagnostics, and links the references back to the knowledge files so the PR author — human or agent — can read the guidance.
## Why this architecture
- **Meta-skills are the only hardcoded thing.** Orchestrators ship with knowledge of `/skills/` and nothing else. New action skills and new knowledge files are picked up automatically.
- **Entry is the only hardcoded thing.** Orchestrators ship with one convention — *"invoke `/skills/entry.md` first"* — and nothing else. New action skills and new knowledge files are picked up automatically because Entry discovers them at dispatch time.
- **Layers decide authority, not code.** The agent sees `/microsoft/` and `/community/` together; if two files conflict, the precedence rule defined in READ resolves it. A partner fork can disable `/community/` — that's a config choice, not a code change.
- **Knowledge and skills evolve independently.** A new knowledge file requires no skill changes — existing skills pick it up via frontmatter filters. A new skill requires no knowledge changes — it sources from what's already there.
## The mental model, in one sentence
The orchestrator knows **when** to run; the meta-skills teach the agent **how** to behave; the action skills define **what** to do; the knowledge files are **what** the agent knows.
The orchestrator knows **when** to run; Entry decides **which skill** to run; the action skills define **what** to do; the meta-skills teach the agent **how** to behave; the knowledge files are **what** the agent knows.

21
skills/README.md
View file

@ -1,16 +1,27 @@
# BCQuality meta-skills
# BCQuality global skills
This folder contains the three global meta-skills — the contracts every consumer of BCQuality depends on. They are small, stable, and layer-agnostic.
This folder contains the skills that are not owned by any single layer. There are two kinds:
If you are an agent being pointed at BCQuality for the first time, read these files in order:
- **The entry-point skill** — the first skill an agent invokes at runtime.
- **The three meta-skill contracts** — stable references that define what the rest of BCQuality means.
## The entry-point skill
| File | Role |
|---|---|
| [`entry.md`](entry.md) | **ENTRY** — Given a task context, returns a dispatch record naming the action skill(s) to invoke. The agent's first call when pointed at BCQuality. |
Routing logic lives in Entry, not in the orchestrator. An agent that knows only "invoke `/skills/entry.md` first" has enough to drive the rest of the repo.
## The meta-skill contracts
| # | File | Role | Who reads it |
|---|---|---|---|
| 1 | [`read.md`](read.md) | **READ** — Schema + Use. How to read a knowledge file: frontmatter fields, section semantics, matching rules, layer precedence, conflict resolution. | Any agent or action skill that consumes knowledge files. |
| 2 | [`do.md`](do.md) | **DO** — Action Skill contract. The Source → Relevance → Worklist → Action template and the structured output every action skill produces. Includes super-skill composition. | Any agent invoking an action skill; every action-skill author. |
| 3 | [`write.md`](write.md) | **WRITE** — New Knowledge. Authoring rules for knowledge files. Defers to `read.md` for the schema. | Contributors (human or agent) who are adding or editing knowledge files. Not used during consumption. |
| 3 | [`write.md`](write.md) | **WRITE** — New Knowledge. Authoring rules for knowledge files. Defers to `read.md` for the schema. | Contributors (human or agent) adding or editing knowledge files. Not used during consumption. |
After reading `read.md` and `do.md`, an agent has everything it needs to pick an action skill from `/microsoft/skills/` or `/community/skills/` and execute it. `write.md` is only needed when scaffolding new content.
READ and DO are read on demand — typically by the first action skill the agent executes after dispatch. They are not prerequisites for invoking Entry. WRITE is only used when scaffolding new content.
These contracts are stable. Changes require a PR approved by both maintainers.

4
skills/do.md
View file

@ -19,7 +19,7 @@ An action skill is a single markdown file with YAML frontmatter. It lives inside
- `/community/skills/` — community-contributed action skills.
- `/custom/skills/` — partner or customer action skills (typically in a consumer repo, not in BCQuality itself).
Action skills do not live at the repo root. The three meta-skills in `/skills/` are the only files that sit outside a layer.
Action skills do not live at the repo root. The files in `/skills/` — the three meta-skill contracts (READ, DO, WRITE) and the entry-point skill (`entry.md`, `kind: entry-point`) — are the only skills that sit outside a layer. The entry-point skill structurally follows this same four-step pattern but produces a dispatch record rather than a findings-report; see `skills/entry.md` for its contract.
## Frontmatter schema
@ -43,7 +43,7 @@ application-area: [all]
`bc-version`, `technologies`, `countries`, `application-area` are optional filters that let an orchestrator pre-select applicable skills for a task. They follow the same semantics as in READ.
`inputs` is a list of abstract input types the skill consumes. Standard values: `pr-diff`, `object-list`, `file-path`, `repository`, `telemetry-query`. `outputs` is always a single-element list naming the output kind; today only `findings-report` is defined.
`inputs` is a list of abstract input types the skill **accepts**. Standard values: `pr-diff`, `object-list`, `file-path`, `repository`, `telemetry-query`. Semantics are any-of: the orchestrator supplies whichever listed input types it has, and the skill is invoked with a non-empty subset of its declared `inputs`. A skill that cannot proceed with the supplied subset MUST return `outcome: "not-applicable"`. `outputs` is always a single-element list naming the output kind; today only `findings-report` is defined.
`sub-skills` is an optional field. When present and non-empty, the skill is a **super-skill** that composes other action skills; see *Composition* below. Values are repo-relative paths to action-skill files.

163
skills/entry.md Normal file
View file

@ -0,0 +1,163 @@
---
kind: entry-point
id: entry
version: 1
title: Entry — route a task to the action skill(s) that apply
---
# Entry
When an agent is pointed at BCQuality to perform a task, it invokes this skill first. Entry returns a **dispatch record** naming the action skill or skills to invoke next. Routing logic lives here, not in the orchestrator.
Entry is its own `kind`: `entry-point`. It structurally follows the DO four-step pattern (Source → Relevance → Worklist → Action) but the units it selects are action skills, not knowledge files, and its output is a dispatch record, not a findings-report.
This contract is stable. Changes require a PR approved by both maintainers.
## Inputs
The agent invokes Entry with a **task context** supplied by the orchestrator:
```yaml
task-context:
goal: string # free-text description of what needs doing
inputs-available: # values the orchestrator has ready to pass to a chosen skill
- pr-diff
- file-path
technologies: [al]
bc-version: 28
countries: [w1]
application-area: [finance]
enabled-layers: [microsoft, community, custom]
disabled-skills: [] # repo-relative paths the consumer has opted out of
```
`goal` and `inputs-available` are required. Filter dimensions (`technologies`, `bc-version`, `countries`, `application-area`) are optional; omitting a dimension is equivalent to "unconstrained" — see Relevance for the exact matching rule. `enabled-layers` defaults to all three. `disabled-skills` defaults to empty.
## Source
All action skills under `*/skills/**/*.md` across the layers named in `enabled-layers`. Meta-skills in `/skills/` (including this file) are not candidates and MUST be excluded. Entry never dispatches Entry.
## Relevance
A candidate is relevant when every condition below holds:
1. Its frontmatter `kind` is `action-skill`.
2. `task-context.inputs-available` intersects its declared `inputs` — the orchestrator has at least one of the input types the skill accepts. A skill is NOT required to accept every input the orchestrator can supply; it is the skill's responsibility to return `outcome: "not-applicable"` if the supplied subset is insufficient.
3. Its frontmatter filter dimensions (`bc-version`, `technologies`, `countries`, `application-area`) match the task context per READ's matching semantics. A dimension omitted from `task-context` is treated as a wildcard and matches any value the skill declares; a dimension explicitly supplied in `task-context` must match the skill's declared values per READ. Conditionally-applicable candidates (any dimension `unknown` per READ) are admitted; they are not filtered out at Entry and are the dispatched skill's concern.
4. Its repo-relative path is not in `task-context.disabled-skills`.
Candidates that fail any condition go to `skipped` with the corresponding reason (`inputs-unsatisfied`, `filter-mismatch`, `configuration`). Skills excluded because they are not `kind: action-skill` are not reported in `skipped`.
## Worklist
Narrow the relevant set to the skills that will actually be dispatched:
1. **Goal match.** Score each candidate's `description` and `id` against `task-context.goal`. Drop candidates that do not plausibly address the goal; record them in `skipped` with `reason: "goal-mismatch"`. Scoring is implementation-defined; agents MUST prefer exact keyword overlap before fuzzy signals.
2. **Super-skill precedence.** When a super-skill and any skill listed in its `sub-skills` are both in the remaining set, the super-skill supersedes the sub-skill **only when the goal is a broader match for the super-skill than for the sub-skill**. When the goal specifically names a concern the sub-skill handles (for example, goal = *"performance review"* with `al-code-review` and `al-performance-review` both present), the sub-skill wins and the super-skill is dropped with `reason: "narrower-sub-skill-selected"`. Otherwise the super-skill wins and each listed sub-skill in the set is dropped with `reason: "superseded-by-super-skill"`. The principle is: Entry dispatches the narrowest skill that satisfies the goal. A dropped sub-skill's `skipped` entry MUST carry `superseded-by` naming the super-skill that won; a dropped super-skill's entry MUST carry `superseded-by` naming the winning sub-skill.
3. **Layer precedence.** When two remaining candidates share the same `id` across layers, keep the highest-precedence one. Skill layer precedence is `/custom/` over `/community/` over `/microsoft/` — the same ordering READ defines for knowledge files. Drop the losers with `reason: "layer-precedence"` and `superseded-by` naming the winning path.
Each dropped candidate appears in `skipped[]` at most once; record the first reason that caused the drop.
The post-filter set is the **dispatch list**.
## Action
Emit a single JSON document conforming to the output contract below. Entry does not invoke the selected skills — that is the agent's responsibility after receiving the dispatch record.
## Output
```json
{
"skill": { "id": "entry", "version": 1 },
"outcome": "routed | no-match | failed",
"outcome-reason": "string",
"dispatch": [
{
"skill": {
"id": "al-code-review",
"version": 1,
"path": "microsoft/skills/al-code-review.md"
},
"rationale": "string",
"inputs": ["pr-diff"]
}
],
"skipped": [
{
"skill": { "id": "string", "path": "string" },
"reason": "inputs-unsatisfied | filter-mismatch | goal-mismatch | layer-precedence | superseded-by-super-skill | narrower-sub-skill-selected | configuration",
"superseded-by": { "id": "string", "path": "string", "version": 1 }
}
]
}
```
### Field semantics
**`outcome`** (required) —
- `routed` — `dispatch` is non-empty; the agent proceeds to invoke each listed skill.
- `no-match` — no action skill applied to the task; `dispatch` is empty. Set `outcome-reason`. Candidates that were considered and dropped MUST appear in `skipped[]`.
- `failed` — Entry itself could not complete (for example, the action-skill folders could not be enumerated, or `task-context` was malformed). Set `outcome-reason`. Agents MUST NOT synthesize a dispatch in this case. This is distinct from an action skill's own `outcome: "failed"` per DO, which applies during skill execution after dispatch.
**`dispatch[]`** — each entry names one action skill to invoke.
- `skill.path` — repo-relative, forward slashes. The agent fetches and executes the file directly from this path.
- `skill.version` — copied from the dispatched skill's frontmatter so the orchestrator can detect drift between dispatch time and execution.
- `rationale` — short human-readable string, for logs and traceability.
- `inputs` — the intersection of `task-context.inputs-available` and the skill's declared `inputs`. The agent MUST pass exactly this subset when invoking the skill. Sending a strict intersection avoids accidental information leakage between skills.
Ordering of `dispatch[]` is not significant.
**`skipped[]`** — MUST list every candidate that was considered and dropped. Each dropped candidate appears at most once; the first drop reason wins. Reasons:
- `inputs-unsatisfied` — `task-context.inputs-available` did not intersect the skill's declared `inputs`.
- `filter-mismatch` — one or more frontmatter filter dimensions explicitly did not match.
- `goal-mismatch` — Relevance admitted the candidate but it failed the goal-match step.
- `layer-precedence` — a higher-precedence skill with the same `id` won. `superseded-by` is required.
- `superseded-by-super-skill` — a super-skill listing this skill as a sub-skill was dispatched instead. `superseded-by` is required.
- `narrower-sub-skill-selected` — a sub-skill listed by this super-skill was dispatched because the goal specifically matched it. `superseded-by` is required.
- `configuration` — the skill is listed in `task-context.disabled-skills`.
**`superseded-by`** — required for `layer-precedence`, `superseded-by-super-skill`, and `narrower-sub-skill-selected`; omitted otherwise. Names the winning skill by `id`, `path`, and `version`.
Empty-dispatch example (no action skills exist in any enabled layer):
```json
{
"skill": { "id": "entry", "version": 1 },
"outcome": "no-match",
"outcome-reason": "No action skills found under */skills/ in the enabled layers.",
"dispatch": [],
"skipped": []
}
```
Populated example (PR review on a repo where only `al-performance-review` is enabled; `al-code-review` and `al-security-review` were disabled by configuration):
```json
{
"skill": { "id": "entry", "version": 1 },
"outcome": "routed",
"dispatch": [
{
"skill": { "id": "al-performance-review", "version": 1, "path": "microsoft/skills/al-performance-review.md" },
"rationale": "Goal 'review pull request' matched; inputs-available contains pr-diff.",
"inputs": ["pr-diff"]
}
],
"skipped": [
{ "skill": { "id": "al-code-review", "path": "microsoft/skills/al-code-review.md" }, "reason": "configuration" },
{ "skill": { "id": "al-security-review", "path": "microsoft/skills/al-security-review.md" }, "reason": "configuration" }
]
}
```
## How the agent uses the dispatch
1. Invoke Entry with the orchestrator-supplied task context.
2. Receive the dispatch record.
3. For each entry in `dispatch[]`, read the referenced action skill, execute its Source → Relevance → Worklist → Action steps per DO, and produce a findings-report.
4. Return the findings-reports to the orchestrator. When `outcome` is `no-match` or `failed`, return the dispatch record itself so the orchestrator can log the reason.
READ and DO are the contracts that govern what the dispatched skills do. An agent that has not yet read READ and DO reads them when it executes the first dispatched skill — they are not prerequisites for invoking Entry.