Comprehension full

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

Skills that know your codebase. Repo-grounded, contract-validated, agent-routable.

Install

npx -y skills add jacob-balslev/skill-graph --skill comprehension-full

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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).

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

8.1 KB, as published. Nobody here has run it

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.