TEMPLATE — copy this directory to start a new skill. Provides folder skeleton, frontmatter contract, section requirements, telemetry schema, and acceptance gate. NOT a real skill — used as the Spine that every published skill (e.g., nist-800-53-rmf) is built from.
Instalação
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
TEMPLATE — copy this directory to start a new skill. Provides folder skeleton, frontmatter contract, section requirements, telemetry schema, and acceptance gate. NOT a real skill — used as the Spine that every published skill (e.g., nist-800-53-rmf) is built from.
category
audit
risk
safe
source
custom
date_added
2026-06-03
tags
["template","spine","scaffold"]
version
0.1.0
status
template
Skill Template (Tier 0 Spine)
This is not a published skill. It is the scaffold that every published skill is built from.
To create a new skill: cp -r skills/TEMPLATE skills/<new-skill-name>, then replace the placeholders.
1. Folder Contract (mandatory)
Every published skill MUST have exactly this layout. The linter (Tier 0a, SOX-616) fails on any deviation.
skills/<skill-name>/
SKILL.md # Frontmatter + body. See §2.
chunks/ # OPTIONAL but REQUIRED if SKILL.md > 300 lines.
# Deep-dive files loaded on demand by the LLM agent.
# See §11 (Context Budget & Chunks Pattern).
01-<topic>.md # Numbered, kebab-case, ≤ 200 lines each.
02-<topic>.md
...
industries/ # ≥3 industry-shaped views of the skill.
_index.md # Industry registry (table: name, file, scope, top use-cases)
financial-services.md # Required for FIN-touching skills; recommended otherwise.
healthcare.md # Required for HIPAA/PHI-touching skills; recommended otherwise.
saas-technology.md # Recommended for IT/cyber skills.
public-sector.md # Required for FedRAMP/CMMC-touching skills; recommended otherwise.
manufacturing.md # Optional.
retail-ecommerce.md # Optional.
energy-utilities.md # Optional.
use-cases/ # ≥3 worked examples with full input/procedure/oracle shape.
_index.md # UC registry (id, title, industries, status, token baseline)
uc-NN-<slug>.md # Standard template (see §4).
data/ # Synthetic datasets + generators (deterministic, seedable).
_index.md # Dataset registry.
README.md # Data dictionary + PII/NPI redaction policy.
generators/ # One .py per dataset, --seed CLI.
seeds/ # Canonical seed fixtures (small/medium/large/edge).
tests/ # Executable test cases.
conftest.py
test_oracle.py # Known-good input → known-good output.
test_grounding.py # Citations resolve, no hallucinated paragraph numbers.
test_trace.py # Output citations match SKILL.md §X.
test_metamorphic.py # Input mutation → expected output mutation.
test_judge.py # LLM-as-judge for qualitative outputs.
test_adversarial.py # Tricky/edge inputs (compensating controls, dual classification).
test_telemetry.py # Token baseline assertions.
test_lint.py # Linter self-check.
telemetry/ # Instrumentation.
schema.json # Per-call event schema (see §6).
instrument.py # Decorator/context-manager that wraps skill invocations.
baseline.md # p50/p90/p99 token use after first run.
redaction.md # PII/NPI redaction rules.
docs/ # Long-form documentation.
architecture.md # How the skill is built and intended to be invoked.
limits-and-disclaimers.md # Anti-hallucination, regulatory currency, known gaps.
changelog.md # Versioned change log.
acceptance-gate.md # Checklist to publish.
Folder-naming rule: kebab-case. Singular. No spaces. No version suffix in folder name.
SKILL.md size rule: If SKILL.md exceeds 300 lines, the chunks/ folder is required and SKILL.md must follow the router pattern (§11). The linter enforces this.
2. SKILL.md Frontmatter Contract
The linter enforces the following YAML fields. All are required unless marked optional.
---name:<skill-name># REQUIRED. kebab-case. matches folder name.description:"<single-sentence activation trigger>"# REQUIRED. ≤1,200 chars. Be specific.category:<audit|legal|finance|...># REQUIRED. one of registered categories.risk:<safe|low|medium|high|critical># REQUIRED. impact of bad output.source:"<provenance string>"# REQUIRED. e.g., "NIST SP 800-53 Rev 5, FIPS 199, OMB A-130"date_added:YYYY-MM-DD# REQUIRED. ISO 8601.version:<semver># REQUIRED. start at 0.1.0.status:<draft|review|published|deprecated># REQUIRED.industries: [<list>] # REQUIRED. See §3. Min 3.frameworks: [<list>] # REQUIRED. ISO/standard identifiers.telemetry_contract:"telemetry/schema.json#/$defs/SkillInvocation"# REQUIRED. JSON pointer to schema.token_baseline_target:# OPTIONAL. Aspirational baseline; revised by real measurement.input_p90:<int>output_p90:<int>context_budget:# REQUIRED. See §11.always_loaded_tokens:<int># tokens of SKILL.md routerper_call_typical_tokens:<int># typical full invocationper_call_max_tokens:<int># worst caseper_call_p90_tokens:<int># measured after first instrumented runtags: [<list>] # REQUIRED. Min 5. Lowercase.---
Naming rule:name MUST equal the folder name. version is MAJOR.MINOR.PATCH and incremented per docs/changelog.md.
3. Body Section Contract
The body MUST have, in order, these top-level sections (##):
§
Title
Required
Notes
1
When to Use / Not Use This Skill
YES
Trigger and anti-trigger lists.
2
Framework Overview
YES
Source, scope, authoritative documents.
3
Core Concepts / Taxonomy
YES
Domain model the skill encodes.
4
Decision Logic
YES
Executable (IF/THEN/ELSE) where applicable.
5
Procedure Templates
YES
Step-by-step playbooks.
6
Output Templates
YES
What the skill produces; paste-able.
7
Cross-References
YES
Mappings to other skills/standards.
8
Worked Examples (high-level)
YES
1-line summaries; full text in use-cases/.
9
Anti-Hallucination Disclaimers
YES
Explicit caveats.
10
References & Citation Manifest
YES
Every cited source with retrieval date.
11
Routing & Context Budget (only if SKILL.md > 300 lines)
YES if applicable
Maps user intent → chunks to load; declares context_budget.
Sections 1-10 are always required and in order. Section 11 is required when the skill uses the chunks pattern (i.e., when the body exceeds 300 lines after §1-§10). Additional sections (e.g., ## 12. Appendix) are allowed but not required.
Every test file follows pytest naming. Tests MUST be deterministic (use seeds, not network). Tests that require an LLM (judge tests) MUST mock the LLM call in CI and gate the real-LLM run behind an env var.
# tests/test_oracle.pyimport json, pathlib, pytest
DATA = pathlib.Path(__file__).parent.parent / "data"
SEEDS = DATA / "seeds"@pytest.mark.parametrize("uc_id,expected", [
("UC-01", {"categorization": "MODERATE", "baseline": "MOD"}),
("UC-02", {"ato_decision": "ATO_WITH_CONDITIONS", "poam_count": 22}),
("UC-03", {"overlap_pct_min": 70, "gap_controls_max": 100}),
])deftest_uc_oracle(uc_id, expected):
inp = json.loads((SEEDS / f"{uc_id.lower()}-input.json").read_text())
out = run_skill(inp) # imported from the skill's invocation entrypoint
assert_oracle(out, expected)
6. Telemetry Schema (required fields)
Every skill MUST publish telemetry/schema.json with this top-level shape. The instrumentation decorator (telemetry/instrument.py) emits one event per invocation.
≥3 industry files, ≥3 use-case files, all with status active.
≥3 test files, all passing locally and in CI.
telemetry/schema.json validates.
telemetry/baseline.md populated after at least one instrumented run on each use case.
docs/architecture.md, docs/limits-and-disclaimers.md, docs/changelog.md, docs/acceptance-gate.md present and non-stub.
No TODO/FIXME outside docs/changelog.md (the linter enforces this).
frameworks: frontmatter list matches citations in §7 of SKILL.md.
Reviewed by the Reviewer agent (3-cycle protocol, see docs/architecture.md).
8. Versioning
MAJOR — breaking change to the skill's decision logic (e.g., new classification rule).
MINOR — new section, new use case, new industry, backward-compatible.
PATCH — wording fix, citation correction, no semantic change.
docs/changelog.md MUST be updated on every change with: date, version, summary, breaking-change flag.
9. Anti-Hallucination Discipline
Every SKILL.md MUST contain a ## 9. Anti-Hallucination Disclaimers section that explicitly flags:
Reconstructed numbering (e.g., ITAF S1-S18, COSO 71/81 Points of Focus).
Citation dates and "verify against current publication" prompts.
Any domain where the skill's output should NOT be relied on without human review.
The line: "This skill encodes domain knowledge; it is not a substitute for professional judgment. Always verify outputs against the cited authoritative source."
10. References & Citation Manifest
## 10. References & Citation Manifest lists every source cited in the body, with:
Title
Author/Publisher
Identifier (e.g., "NIST SP 800-53 Rev 5")
Retrieval date (ISO 8601)
URL (if public)
Local copy path (if bundled under docs/references/)
The linter verifies that every in-body citation of the form [XYZ §N] is listed in this section.
11. Context Budget & Chunks Pattern
LLM context windows are finite. A monolithic SKILL.md of 1,500+ lines costs ~30,000-40,000 tokens per call even when most of it is irrelevant to the user's question. That kills latency, blows the budget, and hurts quality (context rot).
The Spine enforces a context-budget discipline.
11.1 The rule
SKILL.md MUST be ≤ 300 lines. If your skill body is longer, split it.
Above 300 lines, the chunks/ folder is required. SKILL.md becomes a router — it contains the always-loaded preamble, the routing table, and the references manifest. The chunks are loaded on demand.
Each chunk is numbered (01-, 02-, …), kebab-case, and ≤ 200 lines.
Frontmatter context_budget is required (see below). The linter enforces the budget if present.
11.2 Router pattern (what SKILL.md looks like above 300 lines)
SKILL.md (≤ 300 lines, always loaded):
- frontmatter (with context_budget)
- §1 When to use / not use
- §2 Framework overview (one paragraph + table)
- §3 Core concepts (one screen, links into chunks)
- §11 Routing table (maps user intent → chunks to load)
- §12 Operational quick-reference (the minimum cycle)
- §10 References & citation manifest
chunks/01-categorize.md (FIPS 199 + decision logic + procedure + output)
chunks/02-baseline.md (select + tailor)
chunks/03-implement.md (SSP narrative)
chunks/04-assess.md (800-53A + SAR)
chunks/05-authorize.md (ATO + POA&M)
chunks/06-monitor.md (ISCM)
chunks/07-crosswalk.md (other frameworks)
The LLM agent reads the routing table and loads only what's needed. Per-call cost: 3,000-6,000 tokens instead of 30,000+.
11.4 context_budget frontmatter (required)
context_budget:always_loaded_tokens:3000# tokens of SKILL.md router (measured or estimated)per_call_typical_tokens:6000# typical full invocationper_call_max_tokens:15000# worst case (router + all chunks + industry + UC)per_call_p90_tokens:8000# measured after first instrumented run
The linter enforces the 300-line SKILL.md rule, the existence of chunks/ when SKILL.md > 300 lines, and the presence of context_budget in the frontmatter.
11.5 When NOT to use chunks
Skill body ≤ 300 lines — keep it in one file. The overhead of routing is not worth it.
Skill is one-question-one-answer (e.g., a single calculator) — chunks add no value.
Skill is brand new and the body is still moving — keep it monolithic until it stabilizes, then split.
11.6 When to use chunks (always, in practice)
Any skill with decision logic (IF/THEN/ELSE branches, ATO logic, deficiency classification).
Any skill with multiple procedure sections (categorize, select, implement, assess, authorize, monitor, …).
Any skill with multiple output templates (FIPS 199, SSP, SAR, POA&M, ATO letter).
Any skill targeting > 200 lines of body content even if no individual section is large.
If in doubt, split. The cost of routing is one routing table; the cost of monolithic context rot is unbounded.
