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

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

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.