Skip to content

jacob-balslev/skill-graph / examples/fixture-skills/comprehension-full

comprehension-full

Verified

Use 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_state absent.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall