Appendix G — Enterprise structured agent skill standard

This appendix defines a book-specific enterprise engineering standard for packaging, evaluating and governing reusable agent skills. It is an author synthesis informed by emerging Agent Skills conventions and contemporary agent-harness practice; it is not presented as an industry standard.

A skill is a versioned package of procedural knowledge that an agent runtime can discover and load when a task requires it. The architectural objective is to improve specialised behaviour without copying every procedure, reference and example into every inference context.

G.1 Progressive disclosure contract

The skill package should separate three forms of information because they have different context costs and security implications.

The package MUST NOT treat access to a skill as permission to execute a protected capability. Skill selection is a behavioural/context decision; tool authority remains an identity and policy decision enforced by the platform.

G.2 Reference package layout

skills/
  architecture-evidence-review/
    SKILL.md
    references/
      output-contract.md
      evidence-policy.md
    scripts/
      validate_finding.py
    evals/
      activation.jsonl
      task_cases.jsonl
      assertions.py

The public Agent Skills format uses SKILL.md plus optional resources. An enterprise package can add governance metadata and evaluation assets so long as the target runtime supports or safely ignores those additions.

G.3 Recommended SKILL.md

---
name: architecture-evidence-review
description: >
 Review a proposed system against authorised architecture evidence and
 return traceable findings. Use for advisory architecture reviews.
 Do not use to grant formal approval or modify production systems.
version: 1.3.0
owner: enterprise-architecture
risk_class: advisory
---

# Architecture Evidence Review

Use only evidence returned by the authorised architecture retriever.
Return typed Finding objects defined in references/output-contract.md.
Cite at least one evidence identifier for each material finding.
If authoritative sources conflict, return NEEDS_HUMAN_REVIEW.
Do not invoke write-capable infrastructure or repository tools.
Do not represent the result as formal architecture approval.

Descriptions should state the objective, method and trigger conditions clearly enough for semantic routing and should include negative cases where neighbouring skills could be confused. Generic phrases such as “produce high-quality work” add little behavioural information and should be removed.

G.4 Capability and preference skills

For lifecycle management, this book distinguishes two categories.

A capability skill compensates for a model or harness capability that is not yet reliable: a specialised tracing procedure, code scaffold or analytical method. It should be considered temporary and periodically ablated against newer models or runtimes.

A preference skill captures durable organisational intent such as terminology, evidence rules, review criteria, domain playbooks or output contracts. It remains valuable even when foundation models improve because it represents organisation-specific procedural knowledge.

The category controls review cadence, not authority. Both types require evaluation and version control.

G.5 Context-budget rule

Do not enforce an arbitrary universal word limit. Context cost depends on tokenisation, runtime architecture and the amount of metadata exposed continuously. Current public guidance for skill authoring emphasises small always-visible metadata, a concise primary skill body and progressive disclosure of deeper resources. The enterprise should set empirical budgets for:

A larger skill that does not improve measured outcomes is context debt.

G.6 Evaluation harness

No production skill should be promoted without an evaluation suite. A useful minimum contains positive activation cases, negative non-activation cases, task-level behavioural cases and deterministic assertions for machine-checkable invariants. Probabilistic cases should be repeated across multiple trials and across the harnesses/models that the enterprise supports.

Trajectory checks are especially useful when the skill is intended to enforce procedure. Strict matching is appropriate only when order itself is an invariant. Unordered, subset or superset matching is better where the agent may legitimately choose different paths while still being required to use – or prohibited from exceeding – a known tool set. Semantic trajectory judges should be reserved for aspects that deterministic checks cannot decide reliably.

An example evaluation record:

skill: architecture-evidence-review
version: 1.3.0
model_profile: reasoning-medium-2026–08
harness: enterprise-agent-runtime-2.4
trials_per_case: 5
metrics:
 activation_precision: 0.98
 activation_recall: 0.96
 evidence_coverage: 0.94
 forbidden_tool_rate: 0.00
 human_escalation_precision: 0.91
release_gate:
 forbidden_tool_rate_max: 0.00
 activation_precision_min: 0.95
 evidence_coverage_min: 0.90

The values above are illustrative, not universal production targets.

G.7 Ablation and retirement

A skill is maintained through the lifecycle:

author → evaluate → release → observe → ablate → retain | revise | retire.

Ablation means running the protected evaluation suite with and without the skill after a meaningful model, harness or orchestration change. If the skill no longer improves the target behaviour, remove it from production context. Retain the evaluation suite. The tests become a regression sentinel that can detect whether a future model again requires the intervention.

Retirement should also revoke catalogue entries, cached skill content and any skill-specific resource grants. A retired skill must not remain an undocumented shadow dependency.

G.8 Security checklist

G.9 Architecture decision checklist

Use a skill when the behaviour is reusable, conditional, context-sensitive and benefits from progressive disclosure. Prefer deterministic code or a workflow when the procedure is exact, mechanically executable and should not depend on model interpretation. Prefer RAG/knowledge retrieval when the requirement is principally changing factual knowledge rather than procedure. Prefer a policy/rules engine when the requirement expresses mandatory organisational constraints.

The goal is not to maximise the number of skills. It is to place procedural knowledge at the narrowest, most testable boundary that preserves the required flexibility.

References

Anthropic. Skills repository and skill-creator guidance. GitHub, accessed 2026.

Agent Skills Project. Agent Skills specification. GitHub, accessed 2026.

LangChain. AgentEvals. GitHub, accessed 2026.