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

@ -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.