Skip to content

skill-discovery.md

Latest commit

 

History

History
563 lines (468 loc) · 27.8 KB

skill-discovery.md

File metadata and controls

563 lines (468 loc) · 27.8 KB
Raw

Skill Discovery Graph and Index

Renma provides a static, declaration-driven Skill-to-Skill graph, a versioned Skill Index, a compact repository-level Readiness projection, an observation-only direct semantic diff, a CI report projection, and an opt-in warn-only CI review policy. It does not interpret task text, select, rank, load, invoke, or execute a Skill. Repository authors keep routing conditions in source SKILL.md files; Renma exposes deterministic publication, adoption, continuation, and structural evidence.

The current contract is intentionally layered:

explicit continuations and publication
  -> exact route resolution and repository-wide adoption
  -> cycle-safe reachability, coverage, and route-cycle review
  -> renma.skill-index.v1 and the stdout-only skill-index command
  -> compact Readiness, semantic diff, and CI projections
  -> opt-in warn-only CI review policy

Three separate facts

structural root
  = a derived Skill graph fact

published entrypoint
  = an explicit valid Skill-local declaration

repository-wide adoption
  = an explicit repository configuration decision

A structural root is not automatically published. A published entrypoint does not prove complete repository coverage. Neither fact causes Renma to select or execute a Skill.

Canonical declarations

The User Manual's authoritative metadata table owns the complete Renma field inventory. This section intentionally covers only the Discovery-specific renma.published-entrypoint and renma.continues-with subset and its deeper routing semantics.

Only a specification-valid, directory-based Agent Skill named exactly SKILL.md can contribute operational Discovery metadata:

---
name: review-request
description: Classify a review request by workflow. Use when a request needs a reviewed next step; do not use for implementation or runtime Skill selection.
metadata:
  renma.id: skill.review-request
  renma.owner: developer-experience
  renma.status: stable
  renma.published-entrypoint: "true"
  renma.continues-with: '["skill.review-api","skills/review-ui/SKILL.md"]'
---

metadata.renma.published-entrypoint is a one-state marker. The only valid value is the exact YAML string "true"; omission means not published. YAML booleans, "false", empty or whitespace-padded strings, alternate casing, numbers, arrays, objects, null, duplicate declarations, and duplicate top-level metadata mappings fail closed. Renma does not accept published_entrypoint, discovery_entrypoint, entrypoint, renma.entrypoint, or historical aliases, and does not fall back to legacy metadata. Rejected markers retain exact field evidence.

metadata.renma.continues-with uses a JSON-array string contract. Every member must be a non-empty string. An empty array string ('[]') is valid and declares no routes. Renma resolves one exact effective asset ID or one exact repository-relative source path after the documented path normalization; it does not match titles, tags, aliases, basenames, suffixes, prose, or ordinary Markdown links.

Publication eligibility

Publication intent and effective publication are separate. A visible Skill exposes marker state and evidence, whether publication was requested and accepted, stable rejection reasons, and linked existing diagnostics.

A Skill is an effective published entrypoint only when the marker is the exact string "true" and the Skill is:

  • a specification-valid canonical Agent Skill;
  • lifecycle-usable: status is omitted, experimental, or stable; and
  • unique in effective asset ID across the repository catalog.

Stable publication rejection reasons are invalid-marker, ambiguous-marker, invalid-skill, inactive-skill, and duplicate-skill-id. Existing AS-SKILL-* validity diagnostics and META-DUPLICATE-ASSET-ID evidence remain authoritative; Discovery links them instead of emitting competing validity or identity diagnostics.

A suspended Skill remains in the visible Skill inventory with its current lifecycle reason and transition date, but it is not eligible for publication or routing. A valid publication marker on a suspended Skill emits the blocking DISCOVERY-SUSPENDED-PUBLISHED-ENTRYPOINT diagnostic. An active route that resolves exactly to a suspended Skill remains resolved and auditable, but is unusable and emits blocking DISCOVERY-SUSPENDED-ROUTE-TARGET. Suspended Skills and routes are excluded from effective entrypoints, route eligibility, reachability, coverage, and route-cycle analysis. Deprecated and archived publication and route attempts keep their established warning behavior.

A revoked Skill is likewise retained with its current reason and transition date but is unusable for publication and routing. Its valid publication marker emits blocking DISCOVERY-REVOKED-PUBLISHED-ENTRYPOINT; an active route to it emits blocking DISCOVERY-REVOKED-ROUTE-TARGET. These IDs remain distinct from suspension because revocation records explicit withdrawal of trust or authorization, not a temporary stop.

A published Skill may have an incoming route or no outgoing route. A Skill with no outgoing route can itself be a complete first-hop workflow. Graph position never determines publication.

Repository-wide adoption

Repository-wide adoption is declared only in Renma JSONC or JSON configuration:

{
  "skill_discovery": {
    "adopted": true,
    // Keep warning-only while maintainers review migration results.
    "ci_policy": "warn"
  }
}

skill_discovery must be an object. Its supported keys are boolean adopted and string ci_policy. Adoption omission defaults to false; explicit false does not declare repository-wide adoption. ci_policy supports only off and warn, defaults to off, and warn requires adopted: true. Unknown keys, non-string modes, unsupported modes, and alternate spellings are configuration errors. renma init continues to omit this field: initializing Renma is not the same decision as adopting repository-wide Skill Discovery or enabling CI review policy.

The prepared Discovery index reports one deterministic adoption state:

  • not-adopted: no continuation or publication metadata is present and repository-wide adoption is not true;
  • partial: valid, invalid, or rejected continuation/publication metadata is present and repository-wide adoption is not true;
  • incomplete: repository-wide adoption is true but no effective published entrypoint exists; or
  • adopted: repository-wide adoption is true and at least one effective published entrypoint exists.

Reachability and coverage

Published entrypoints define where Discovery starts. Usable continues-with routes define where Discovery can continue. Reachability reports what can be found through those declarations. Renma still does not decide which Skill matches a user request.

Traversal starts from every effective published entrypoint at depth 0 and uses only routes that are usable representatives, resolve successfully, and target a Skill. Resolution and usability are not reinterpreted during traversal. Invalid, inactive, duplicate-ID, unresolved, ambiguous, wrong-kind, and duplicate non-representative declarations therefore cannot create reachability. Adjacency, entrypoint provenance, and result IDs are sorted; per-entrypoint breadth-first traversal gives the true minimum route depth and terminates safely through self-loops and larger cycles.

Route-cycle review diagnostics

Renma detects maximal strongly connected components after route resolution and usability are complete. The input is exactly the existing authoritative continuation edge boundary:

route.usable === true
route.representative === true
route.resolution === "resolved"
route.resolvedTarget.kind === "skill"

Invalid, inactive, duplicate-ID, unresolved, ambiguous, wrong-kind, normalization-rejected, and duplicate non-representative declarations cannot participate. Ordinary Markdown references, Context relationships, reachability, structural-root state, and directory layout never create cycle edges.

A singleton component emits DISCOVERY-ROUTE-CYCLE only when its one Skill has an explicit self-loop. A component with two or more Skills emits one warning for the complete maximal component, including every usable representative internal route. Sorted adjacency, members, routes, and component sequences make the result independent of document, declaration, Map, and Set insertion order. The canonical first internal route supplies the warning's primary path and exact renma.continues-with evidence.

A cycle is static continuation evidence. It does not prove that an agent will recurse or execute the same Skills repeatedly. Renma traversal is cycle-safe. A cycle may be intentional, but every internal continuation and the workflow's stop, ask, retry, handoff, and completion conditions should be reviewed. An intentional bounded cycle may remain after review; Renma does not choose an edge to remove or change reachability.

Every visible Skill exposes one reachability object:

  • reachable: an effective entrypoint or an eligible Skill reached through usable declarations, with every reaching entrypoint ID and minimum depth;
  • not-reached: an eligible Skill with no usable path when coverage is being evaluated; or
  • not-evaluated: repository coverage is not evaluated, or the Skill itself is not Discovery-eligible.

Coverage always has repository scope and uses one of three modes:

  • not-evaluated: Discovery is not-adopted, incomplete, or partial without an effective published entrypoint. Reachable and not-reached arrays remain empty. Readiness reports this as unevaluated rather than presenting the empty arrays as 0 reachable and 0 not-reached. The check is neutral for not-adopted; it warns only when Discovery metadata or explicit repository-wide adoption makes the missing effective entrypoint actionable.
  • descriptive: adoption is partial and at least one effective published entrypoint exists. Reachability is review evidence, not a repository-wide completeness claim, and not-reached Skills do not emit coverage warnings.
  • authoritative: adoption is adopted. complete is true only when every Discovery-eligible Skill is reachable; otherwise it is false and each not-reached eligible Skill emits a warning.

The index exposes sorted reachableDiscoveryEligibleSkillIds, notReachedDiscoveryEligibleSkillIds, and unroutedSkillIds. Unrouted means exactly an eligible structural root that is not an effective published entrypoint; it is not a synonym for not-reached. A disconnected child can be not-reached while still having an incoming usable route and therefore not be unrouted.

Graph view

All Discovery formats use the same index prepared in the shared repository snapshot:

renma graph . --view discovery --format json
renma graph . --view discovery --format markdown
renma graph . --view discovery --format mermaid
renma graph . --view discovery --focus skill.review-request --format json

JSON includes adoption, repository-scoped coverage, published, reachable, not-reached, structural-root, standalone, and unrouted ID arrays in the dedicated discovery object. Each visible Skill includes ownership provenance, structural-root and standalone facts, marker evidence, publication request and acceptance, rejection reasons, global reachability, unrouted state, and linked diagnostics. Repository diagnostics remain at top-level diagnostics; Skill Discovery diagnostics remain under discovery.diagnostics. Exit-code evaluation considers errors in both collections, while current Discovery diagnostics are warnings.

Markdown presents Summary, Adoption, Coverage, Published entrypoints, authoritative coverage gaps when adopted, Structural roots, Unrouted Skills, Declared routes, Discovery diagnostics, and then Repository diagnostics when present. Descriptive mode shows counts without presenting not-reached Skills as defects. Long structural and coverage lists are bounded; JSON retains the full arrays.

Mermaid retains solid usable route edges and dotted unusable declaration edges. Published entrypoints and structural roots receive separate deterministic classes, including both facts when one Skill has both roles. Styling does not change edge meaning or imply invocation. Deterministic comments record coverage mode plus source-entrypoint, reachable, not-reached, and unrouted ID arrays.

Exact --focus retains the selected Skill's direct incoming and outgoing declarations without transitive traversal. A focused projection preserves the repository-wide adoption and coverage objects and every visible Skill's global reachability. Published, reachable, not-reached, and unrouted ID arrays plus summary counts are filtered to visible Skills. Focus never becomes a traversal seed and never recomputes coverage or cycles from the subset. Repository-wide cycle diagnostics remain visible whenever any recorded internal cycle route is part of the focused direct-neighborhood route projection. Focusing an unrelated Skill excludes the diagnostic; focus does not become transitive.

Skill Index command

renma skill-index emits a compact static index over the same prepared Discovery model:

renma skill-index .
renma skill-index . --format markdown
renma skill-index . --format json
renma skill-index . --json
renma skill-index . --focus skill.release-prep --format markdown

Markdown is the default. JSON uses the canonical schema identifier renma.skill-index.v1 and is the complete unfocused automation contract. The report contains repository metadata, the existing adoption, coverage, summary, visible Skill, route, publication, reachability, structural-root, standalone, unrouted, and eligible-ID projections, plus explicitly separate diagnostics.repository and diagnostics.discovery collections.

The command collects one RepositorySnapshot and wraps its already prepared Discovery index. It does not scan twice or reimplement parsing, exact target resolution, eligibility, publication, reachability, coverage, or focus. Repository diagnostics remain repository-wide. Focused Discovery diagnostics use the existing exact direct-neighborhood projection.

Focus accepts only an exact stable effective Skill ID or exact repository-relative Skill source path. It does not match titles, descriptions, tags, aliases, basenames, suffixes, letter-case variants, fuzzy phrases, or task text. Focus does not perform transitive traversal and does not make the selected Skill reachable. In focused reports:

coverage is repository-scoped

summary and visible ID arrays are projection-scoped

Markdown shows the static-only boundary, summary, adoption and coverage, focused Skill when present, effective published entrypoints and their direct continuations, authoritative coverage gaps, structural candidates, separate diagnostic sections, and instructions to open the referenced source SKILL.md. Long presentation lists use the established deterministic cap; JSON retains complete evidence.

The command writes only to stdout. It does not create .renma/, write a generated index, modify configuration or Skill metadata, interpret a request, select or rank a Skill, load Context, assemble a prompt, infer a route, call an LLM, or execute a workflow. Exit 0 means the report was produced with no error-severity diagnostic; warnings still exit 0. Exit 1 means an error is present in either diagnostic collection. Invalid CLI use, configuration, focus, or report construction exits 2.

Diagnostics

Discovery publication uses these warning diagnostics:

  • DISCOVERY-INVALID-PUBLISHED-ENTRYPOINT for an invalid or ambiguous marker, or an exact marker on a specification-valid inactive Skill; and
  • DISCOVERY-ENTRYPOINT-WITHOUT-USABLE-BOUNDARIES when current deterministic Agent Skills checks establish that an effective entrypoint lacks a capability, positive usage boundary, or negative selection boundary.

The boundary warning reuses linked RN-SKILL-* evidence and is not proof of semantic completeness. Its repair is to improve the bounded first-hop responsibility, not to remove publication solely to silence the warning.

Both diagnostics flow through normal scan output, diagnostics v2, and review bundles. They do not create a CI gate. Readiness may reference their stable codes and messages as compact check evidence without copying them into its diagnostic collection. The semantic diff and neutral CI projection compare prepared topology facts but do not copy these diagnostics; Trust Graph and BOM remain excluded.

DISCOVERY-UNREACHABLE-ELIGIBLE-SKILL appears only in authoritative adopted mode, once per not-reached eligible Skill. It states the exact negative graph fact: no usable declared continuation path reaches the Skill from any effective published entrypoint. It does not claim runtime non-use and does not recommend a fake route or blanket publication. Repair requires human review of whether the Skill is an independent first hop, belongs beneath a real source-owned workflow, or falls outside the intended repository-wide policy. This warning also flows through scan, diagnostics v2, and review bundles. Readiness uses it as the authority for adopted-mode coverage check evidence without duplicating the diagnostic or applying another score penalty. Its diagnostic payload remains outside Trust Graph, semantic diff, CI, and BOM projections.

DISCOVERY-ROUTE-CYCLE does not require repository-wide adoption. It is emitted whenever the prepared usable continuation graph contains a cyclic strongly connected component, including a self-loop. In normal repository states this means partial, incomplete, or adopted: a truly not-adopted repository has no Discovery metadata and therefore cannot contain a usable declared route cycle. Details contain sorted cycleSkillIds, cycleSkills, selfLoop, routeCount, and complete cycleRoutes evidence. Every member Skill and internal route links the diagnostic. The warning asks a human to decide whether the component is an intentional bounded workflow loop or an accidental circular continuation contract; it does not require every intentional cycle to be removed.

Cycle warnings flow through scan, diagnostics v2, review bundles, Discovery graph diagnostics, Skill Index Discovery diagnostics, and the compact Readiness cycle-review check. They remain warnings, do not create a CI gate, and do not by themselves make Readiness fail. Discovery JSON report schemas, Markdown sections, and Mermaid edge semantics are unchanged; there is no top-level cycle section or count in the Discovery graph or Skill Index.

Readiness projection

Readiness exposes routine-review visibility under readiness.summary.skillDiscovery. The summary is derived only from the memoized prepared Discovery index in the shared RepositorySnapshot and contains the existing adoption state plus compact publication, eligibility, reachability, unrouted, route-usability, unresolved-route, and maximal cycle-component counts. It contains no complete Skill array, route list, or diagnostic payload.

The five Readiness checks use the established lower-case dotted ID style:

  • discovery.publication reviews explicit effective publication only. not-adopted repositories pass because publication is not required and structural roots are never inferred as published. Partial or incomplete adoption without an effective published entrypoint warns, while valid effective publication and existing publication diagnostics remain authoritative;
  • discovery.route_validity aggregates existing resolution and usability reasons;
  • discovery.coverage is authoritative only for explicit repository-wide adoption, descriptive only for partial adoption with an effective entrypoint, and explicitly unevaluated when Discovery is not adopted or no effective entrypoint exists;
  • discovery.unrouted_skills preserves the existing unpublished/no-incoming usable continuation definition and does not reject intentional standalone Skills automatically; and
  • discovery.cycle_review counts maximal cyclic components as warning-level human review evidence.

This projection adds no scoring weight. Partial coverage never reduces the score, cycle presence alone is not a hard failure, and existing Discovery diagnostics are referenced rather than copied or penalized again. Use renma skill-index for the complete static report and renma graph --view discovery for topology and source evidence.

The direct Readiness command prepares the memoized Discovery projection once. Semantic diff retains its Discovery-excluded Readiness subset, then uses the same snapshot's prepared Discovery index for its dedicated versioned section. CI calls that complete semantic diff once and projects its existing SkillDiscoveryDiff; it therefore intentionally prepares one Discovery index per ref without a second collection or comparison. BOM continues to build and serialize its Discovery-excluded Readiness subset without preparing Discovery for that subset.

Semantic diff projection

Direct renma diff JSON and Markdown include an observation-only discovery section. It reports exact from/to adoption and coverage modes, count deltas, effective published entrypoint additions/removals, newly-reachable and newly-not-reached Skills, newly/resolved unrouted Skills, route additions/removals/state changes, and added/resolved maximal cyclic components. Count deltas use to - from; identity lists remain present because equal additions and removals can cancel numerically.

Skill identity is repository-relative path plus visible ID. Route identity is normalized source Skill path plus normalized declared target. It deliberately excludes declaration index, YAML array position, source line, discovery order, resolved target, and object insertion order. Declarations with the same route identity form one group whose declarationCount records duplicate changes. Reordering declarations therefore produces no diff. A resolution, candidate, resolved-target, lifecycle, usability, or reason change under the same identity is one changed route; only identity presence determines route addition or removal.

Cycle identity is the sorted maximal strongly connected component member-ID set. Internal edge order does not create a resolved-plus-added cycle pair; edge changes remain route changes. Reachability uses only the prepared reachable/not-reached partitions, and empty sets stay empty when coverage is not evaluated. Structural roots are never inferred as publication.

Each archived ref is collected once into one immutable RepositorySnapshot. Graph, the Discovery-excluded Readiness subset, and snapshot.skillDiscovery therefore share one parse, catalog preparation, Agent Skills validation, and Discovery preparation per ref. The diff does not call skill-index, reconstruct Discovery independently, or copy its complete report or diagnostics.

These facts have no improvement/regression label and do not change direct diff exit behavior.

CI report projection and review policy

Renma exposes the exact existing SkillDiscoveryDiff once as required top-level CiReport.skillDiscovery. Its schema remains renma.skill-discovery-diff.v1; CI does not construct a second Discovery schema or comparison. The nested CiCompatibleDiffReport under diff omits discovery, preserving the compact earlier contract and avoiding duplicate JSON.

CI uses the internal semantic-diff execution exactly once. Each ref therefore uses one immutable RepositorySnapshot, one discovery pass, one parse per artifact, one catalog preparation, one Agent Skills validation, and one Skill Discovery preparation. Graph, the Discovery-excluded Readiness subset, Discovery facts, and that ref's effective skillDiscovery.ciPolicy reuse the same snapshot. There is no second diff, config load, repository discovery, or Discovery preparation.

Reports also contain one top-level skillDiscoveryPolicy value:

schemaVersion: renma.skill-discovery-ci-policy.v1
configured: { from, to, effective }
outcome: pass | warn
matchCount
matches

The effective mode uses the stricter archived-ref value under off < warn. Thus off -> warn and warn -> off both evaluate as warn; a pull request cannot bypass review merely by disabling the policy in its target config. When effective mode is off, evaluation returns pass, zero matches, and no hypothetical results.

Enabled policy evaluation uses only these stable match IDs and conditions:

  • skill_discovery_ci.adoption_weakened: adoption moves from adopted or incomplete to partial or not-adopted;
  • skill_discovery_ci.adoption_incomplete: target adoption is incomplete;
  • skill_discovery_ci.newly_not_reached: one match per existing reachability.newlyNotReached Skill, only with authoritative target coverage;
  • skill_discovery_ci.route_became_unusable: one match per changed route whose usable state changes from true to false, only with authoritative target coverage; and
  • skill_discovery_ci.added_unusable_route: one match per added route whose usable state is false, only with authoritative target coverage.

Removed entrypoints, newly unrouted Skills, removed routes, declaration-count-only changes, newly reachable Skills, resolved not-reached Skills, routes becoming usable, adoption becoming authoritative, cycles and self-loops, partial/not-adopted coverage observations, and count deltas without matching identities do not create policy matches. In particular, a cycle is review evidence rather than an automatic defect.

CI Markdown places a bounded ## Skill Discovery Changes section after the semantic-diff summary. It reports policy configuration and outcome plus adoption, coverage, publication, reachability, unrouted Skills, route changes, cycle changes, and bounded policy matches. Detailed lists use the shared top-summary cap and direct readers to JSON for omitted entries. It does not render the complete graph, diagnostics, declaration indices, source lines, or repair instructions.

determineCiReportStatus() remains typed only over the Discovery-free compatible diff. A separate pure composition keeps fail > warn > pass: an existing FAIL remains FAIL, an existing WARN remains WARN, and an existing PASS becomes WARN only when policy outcome is warn. One concise policy review note is appended for matches. Discovery policy cannot produce FAIL, and its WARN exits 0.

Serialized CI reports that predate both Discovery fields retain their prior JSON and Markdown shape. A report with skillDiscovery but no skillDiscoveryPolicy retains its observation-only section. Formatting does not mutate either legacy generation.

Programmatic compatibility is preserved separately from the direct command contract. buildDiffReport() accepts older snapshots without prepared Discovery indexes and returns a stable neutral Discovery section rather than inferring topology. formatDiff() accepts older serialized reports without discovery and retains their previous non-Discovery Markdown shape.

Compatibility and boundaries

Continuation and publication data remain separate from catalog.dependencies. Existing full, summary, workflow, layered, composition, and impact graph outputs remain route/publication-free. Catalog, Trust Graph, BOM, ownership, init, scaffold, guide, and suggestion contracts are unchanged. Readiness changes only through its additive summary and checks; direct diff changes only through its additive observation section; CI adds the neutral projection and explicit warn-only policy. A repository without Discovery policy opt-in remains valid and policy-neutral. Its not-adopted Readiness summary is a neutral inventory summary: route-eligible, unrouted, and route counts remain visible, while publication is not required and coverage is not evaluated.

There is no renma discovery command. Hard-fail gating, per-rule configuration, policy suppressions or allowlists, Trust Graph, BOM, ownership, observed Markdown references, richer visualization, authoring assistance, scaffold, init, guide, suggestion, and multi-repository federation are outside this contract. BOM and Trust Graph output contracts contain no Discovery additions.