74 lines
7.0 KiB
Plaintext
74 lines
7.0 KiB
Plaintext
---
|
|
id: skills-governance
|
|
title: Skills governance
|
|
description: Contract, lifecycle, decision rights, adapters, locking, exceptions.
|
|
---
|
|
|
|
|
|
<div className="strategy-content">
|
|
|
|
**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
|
|
|
|
### A contract that travels, controls that stay authoritative
|
|
|
|
Maintain one catalog entry per stable skill ID, with immutable revisions and a concise portable `SKILL.md` body. Required content includes when to use and when not to use the skill, prerequisites, bounded steps, expected artifacts, verification, failure handling and escalation. The catalog contract below defines owner and independent reviewer, risk tier, supported clients and versions, dependencies, digest, provenance and license, evaluations, approval, review date, deprecation and rollback.
|
|
|
|
The release manifest pins the content, dependencies and adapter revisions by full immutable commit or digest. Names use an `eldorado-` prefix to reduce collisions. Friendly versions aid communication but never replace the digest. No arbitrary upstream automatic update is admitted into the approved bundle. Changes to scripts, resources or dependencies count as skill changes, not harmless documentation edits.
|
|
|
|
Adapters place content in the qualified client's discovery paths and implement only verified client-specific behavior. Qualification records the host, exact build, OS, model configuration, discovery, explicit invocation, collisions, disabled skills, permission behavior, context compaction and reload behavior. A common file format is not common precedence or a portable hooks API. Claude and Cline skill-name precedence differs from rule/memory behavior; Copilot support varies by surface. Test the actual build, not the brand name.
|
|
|
|
### Lifecycle and decision rights
|
|
|
|
A proposal names the problem, owner, data scope and testable outcome. Experimental revisions run only in approved disposable environments. Promotion requires independent review, static and executable dependency checks, per-client behavioral evaluations and a bounded canary. Approval records bind the exact artifact and permitted uses. Deprecated revisions carry a migration path and deadline; retired revisions are unavailable for new work. Any active revision can be quarantined immediately.
|
|
|
|
The author never supplies the only approval. Data & AI maintains catalog state; the owning team is accountable for content; Quality Engineering approves evaluation evidence; Architecture & Security approves higher-risk boundaries; Platform & IT verifies distribution and revocation. A business owner accepts workflow outcomes. These functions can be covered by existing staff, but incompatible author/approver duties must remain separate for the same release.
|
|
|
|
An exception contains its ID, skill/client revision, scope, business reason, risk owner, compensating checks, approver, start and expiry, affected users/projects and rollback route. It does not disable protected release, payment or identity controls. Expired or unverifiable exceptions deny privileged actions. Repeated exceptions trigger a supported-design change rather than permanent informal bypass.
|
|
|
|
### Distribution, stale clients and rollback
|
|
|
|
Stage a verified bundle atomically, check its digest, load it through the qualified adapter and read back its effective revision. Test already-open sessions; changing files is not proof of reloading instructions. Record immutable last-known-good content and adapter dependencies. Canary upgrades precede wider distribution.
|
|
|
|
A cached verified bundle may support explicitly permitted low-risk work if its model and tool dependencies are available. It does not make a cloud-backed client work offline. Stale or unsupported sessions cannot obtain centrally mediated privileged access. Reconnection revalidates support, revocation and policy before credentials are issued. Central artifact review protects delivery even when a laptop declaration is absent or false; a client report cannot prove which private prompt was actually followed.
|
|
|
|
Rollback restores the approved manifest and dependencies, invalidates affected sessions, revokes unsafe revisions, runs a smoke test and verifies effective state. It cannot undo data disclosure or commands already executed. Those require incident response.
|
|
|
|
## Catalog contract
|
|
|
|
| Contract | Definition |
|
|
| --- | --- |
|
|
| skill_id | Stable globally unique eldorado-<domain>-<purpose>; never reused for a different purpose |
|
|
| name | Human-readable name |
|
|
| purpose | Problem, expected outcome and intended users |
|
|
| triggers | Positive and negative invocation conditions |
|
|
| owner | Existing department/team plus assigned accountable person before approval |
|
|
| reviewer | Independent person and existing team; cannot equal release author |
|
|
| backup | Named coverage within existing team before production support |
|
|
| risk_tier | R1\|R2\|R3; maximum implied by data, tool and effect scope |
|
|
| data_classification | Allowed input/output/provider boundary and forbidden data |
|
|
| authority_envelope | Allowed resources/operations and forbidden effects; enforced externally |
|
|
| supported_clients | Array of client, host, exact tested builds, OS, model configuration, adapter digest and qualification evidence |
|
|
| dependencies | All skill/resource/script/tool/MCP/plugin dependencies pinned by immutable digest plus license and source |
|
|
| revision | Full immutable source commit and content/artifact digest; friendly semver optional |
|
|
| tests_evals | Suite/corpus/rubric/runner/judge revisions, client tuple, seeds or trial IDs, results and independent evidence refs |
|
|
| approval | Approver identities, exact digest and policy revision, approved scope, time and expiry/invalidation condition |
|
|
| provenance_license | Origin repository/author, upstream revision, acquisition/review history, rights/license for content and bundled resources |
|
|
| maintenance_date | Last substantive review timestamp plus next review due and trigger conditions |
|
|
| deprecation | State, reason, replacement, migration instructions, consumers and retirement deadline if applicable |
|
|
| rollback | Approved known-good bundle+adapter+dependency digests, revocation/reload procedure and tested evidence |
|
|
| procedure | Prerequisites, bounded steps, expected artifacts, verification, failure handling, escalation |
|
|
|
|
|
|
## Promotion and retirement
|
|
|
|
| Transition | Required evidence |
|
|
| --- | --- |
|
|
| proposed → experimental | Owner, purpose, risk/data scope, disposable environment and preregistered test plan |
|
|
| experimental → approved | Independent review, all mandatory tests, qualified clients, canary, exact-digest approval |
|
|
| approved → deprecated | Owner gives migration/replacement and retirement conditions |
|
|
| deprecated → retired | Consumers reconciled or explicit risk-approved cutover; no new invocation |
|
|
| any active state → quarantined | Incident or unsafe/unknown provenance; central deny immediately |
|
|
| quarantined → experimental | Reviewed correction; new immutable revision; requalify, never auto-restore approval |
|
|
|
|
</div>
|