How competencies and evidence connect
This is the first of three pages on creating quality content for learners. This one is the wiring diagram — which fields on a task point at which other files, and what each one is actually for. Designing competencies and levels and Writing tasks that produce real evidence build on it with the pedagogical judgment calls the format itself can't make for you.
A task is a hub, not a container
A task never embeds a competency's or resource's content — it only carries their ids, and the app resolves each one against the shared library:
{
"schemaVersion": 1,
"id": "y1t1-004",
"title": "Rebase a feature branch cleanly",
"term": "year-1/term-1",
"module": "git",
"estimatedHours": 3,
"competencies": ["git"],
"resources": ["pro-git"],
"aiPolicy": { "mode": "guided", "allowedCapabilities": ["explain", "hint", "quiz"] },
"evidence": [
"Git history showing an interactive rebase, not a squashed rewrite",
"A short note explaining one conflict you resolved and why"
],
"acceptanceCriteria": [
"Feature branch is rebased onto the current main with no merge commits",
"At least one resolved conflict is described in the submission note"
]
}- •competencies — ids resolved against competency files. This is the only place a task declares what it's actually measuring.
- •resources — ids resolved against resource files. Reading material, not measurement.
- •evidence and acceptanceCriteria — plain strings, not ids. Nothing else resolves them; they're instructions to the apprentice and a checklist for the mentor, written directly on the task.
- •aiPolicy — a self-contained object, covered on its own page: Setting the AI policy for a task.
What a competency file actually is
{
"schemaVersion": 1,
"id": "git",
"title": "Git",
"description": "Git data model, commits, branching, merging...",
"levels": [
{ "level": 1, "name": "Foundation", "description": "..." },
{ "level": 2, "name": "Apprentice", "description": "..." },
{ "level": 3, "name": "Practitioner", "description": "..." },
{ "level": 4, "name": "Journeyman", "description": "..." },
{ "level": 5, "name": "Mastery Evidence", "description": "..." }
]
}Every competency carries the same five levels — Foundation, Apprentice, Practitioner, Journeyman, Mastery Evidence — each with its own description of what that level of ability looks like. A task doesn't pick a level; it just says "this task is evidence toward this competency," and levels accumulate from how many approved tasks reference it. See Tracking competency growth for exactly how that's computed today, and Designing competencies and levels for how to write level descriptions that actually hold up.
Shared by id, overridable per curriculum
Resource and competency files live once, shared by every curriculum in a working copy — see Curriculum structure basics. That sharing is resolved by id, not by convention: when a task in a multi-curriculum repository references "git", the app looks first for a file with that id inside that curriculum's own folder, and only falls back to the shared root file if none exists there. Use that to give one curriculum a genuinely different take on a shared competency; don't use it to fork a copy you intend to keep identical — that's what the shared file is for.
A shared id is a promise: every curriculum in that repository that references "git" is claiming the same real-world capability, measured the same way. If two curricula's ideas of "git" genuinely diverge, give one of them its own id rather than quietly overriding the shared meaning.
What a submission's evidence actually looks like
A task's evidence field is a set of expectations you write for the apprentice — what you want them to be able to point at. What they actually submit is simpler: an evidence note attached to the submission alongside their reflection. Write your evidence array as the checklist that note should satisfy, not as a form with separate fields for each item — today's submission flow is one honest note, not a multi-part evidence picker.
Keep evidence and acceptanceCriteria pointed at each other: every acceptance criterion should be checkable from something the evidence list actually asks the apprentice to produce. An acceptance criterion with no matching evidence expectation is a criterion your mentor can't actually verify.
Translatable, but not the ids
Evidence expectations, acceptance criteria, and a competency's level descriptions are all translatable overlay fields. Competency and resource ids never are — see Locale overlays for the full allow-list and why identity fields stay locked.