jacob-balslev/skill-graph / examples/fixture-skills/comprehension-full
comprehension-full
VerifiedUse as the v8-conformant fixture exercising the full Understanding surface — the five flat top-level fields (mental_model, purpose, concept_boundary, analogy, misconception) in SKILL.md frontmatter, paired with comprehension_state: present in the audit-state.json sidecar. Activate this skill when verifying that the cross-file lint accepts the flat Understanding fields when the sidecar declares comprehension_state: present. Do NOT use as a production skill (use a real capability skill from the canonical library).
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |