jacob-balslev Comprehension-Full Fixture
This fixture exercises the full Understanding surface in the canonical
v8 post-sidecar shape: the five flat top-level fields (mental_model,
purpose, boundary, analogy, misconception) live in SKILL.md
frontmatter, and comprehension_state: present lives in the
audit-state.json sidecar. The cross-file lint check (per ADR-0019)
must accept this pairing — when the sidecar declares
comprehension_state: present, the five frontmatter fields are required.
Concept of the skill
What it is: The Understanding surface is the set of five flat frontmatter fields the comprehension grader reads, declared present by the sidecar's comprehension_state flag.
Mental model: Two files, one contract — frontmatter holds the teaching prose, the sidecar holds the bookkeeping flag, and a cross-file lint binds them.
Why it exists: To prove the post-sidecar split (ADR-0019) keeps the comprehension contract enforceable without the retired nested concept block.
What it is NOT: It is not a passing comprehension eval (eval_state) and not routing (routing_eval); presence of the fields is not a quality verdict.
Adjacent concepts: the comprehension grader, comprehension_state, the legacy nested concept block.
One-line analogy: The flat fields are a book's index; the sidecar flag is the catalog card recording the index exists.
Common misconception: That comprehension_state: present means the eval passed — it only means the reading surface exists.
Coverage
The five flat Understanding fields in frontmatter plus
comprehension_state: present in the audit-state sidecar, proving the
cross-file comprehension contract. No grounding (ambient — no
project[], public: true), no relations.
Philosophy of the skill
Per ADR-0019,
agent-facing fields (including the flat Understanding prose) live in
frontmatter, while audit/eval bookkeeping (including comprehension_state)
lives in the sidecar. The legacy nested concept block was retired in the
clean cut. This fixture is the smallest configuration that proves the
cross-file lint binds the sidecar flag to the frontmatter Understanding
fields without re-introducing the nested block.
Verification
node scripts/skill-lint.js --path examples/fixture-skills/comprehension-full
# expected: 0 errors
node scripts/skill-lint.js --path examples/fixture-skills
# expected: 0 errors across all four fixtures
The cross-file lint must accept the split shape: comprehension_state: present in audit-state.json satisfied by the five flat top-level
Understanding fields in SKILL.md frontmatter. That contract is
documented in SKILL_METADATA_PROTOCOL.md § Understanding.
Do NOT Use When
- You need to test the bare-minimum frontmatter — use
minimal-capability. - You need to test codebase grounding — use
with-grounding. - You need to test typed relations — use
with-relations. - You need to test frontmatter with no comprehension surface at all — author a separate fixture or use a real capability skill with
comprehension_stateabsent.