A skill library makes reusable procedures available for agent selection. Keeping it reliable requires tracking which Skills were eligible, what was selected, and how the run performed—not just counting uses. section 7.4.5
Maintain the library as an evidence-backed lifecycle:
- Record task conditions, eligible and selected versions, agent and Harness versions, dependencies, outcomes, costs, failures, and corrections. section 7.4.5
- Review for duplicates, uncovered tasks, misrouting, conflicts, dependency changes, context cost, and outdated versions. Choose to keep, refine, merge, demote, deprecate, or retire. section 7.4.5
- Treat low use as a reason to review, not automatically demote; critical but rare Skills may still be needed. section 7.4.5
- Make withdrawal evidence-backed and reversible, with a rollback version; require authorized approval for changes affecting safety or production boundaries. section 7.4.5
Listing 7.14 Operating evidence and reversible withdrawal
@dataclass(frozen=True)
class SkillRunEvidence:
task_family: str
legal_versions: tuple[str, ...]
selected_version: str | None
agent_version: str
harness_version: str
dependencies: dict[str, str]
outcome: str
evidence_ids: tuple[str, ...]
@dataclass(frozen=True)
class WithdrawalEvidence:
reason: str
evidence_ids: tuple[str, ...]
reversible: bool
rollback_version: str
approval_id: str | None = None
def withdraw_skill(
registry,
skill,
evidence,
) -> bool:
if not evidence.reason or not evidence.evidence_ids:
return False
if not registry.valid_evidence(evidence.evidence_ids, skill):
return False
if not evidence.reversible: #A
return False
if not registry.has_version(
skill.skill_id,
evidence.rollback_version,
):
return False
protected_scope = registry.is_protected(skill) #B
if protected_scope and not registry.valid_approval(
evidence.approval_id,
skill,
):
return False
with registry.atomic_change(): #C
registry.archive(skill, evidence.rollback_version)
registry.remove_from_routes(skill.skill_id, skill.version)
registry.record_withdrawal(skill, evidence)
skill.state = SkillState.DEPRECATED
return True
A registry-facing withdrawal example checks evidence and reversibility before changing Skill availability. section 7.4.5
