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

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.