The datarim-system Skill — The Core Rules Every Agent Loads First
A look at the datarim-system skill — the always-loaded ruleset that defines where Datarim state lives, how task files are structured, and how agents resolve paths and load order.
Before any /dr-* command does anything, it reads datarim-system. This skill is the foundation layer: it defines where workflow state lives, what the operational files must look like, and how the framework resolves paths and skill loading order. Every other skill and every agent treats it as a prerequisite.
Operational files are indexes, not content
The central rule in the skill is that tasks.md, backlog.md, and activeContext.md are indexes. Each bullet line answers four questions — which task, what state, what complexity level, and where the description file is — and nothing else. A task description file at datarim/tasks/{TASK-ID}-task-description.md holds all the actual content: overview, acceptance criteria, constraints, out-of-scope notes, and related references.
Two files are explicitly abolished. progress.md no longer exists as of v1.19.0 — per-task progress notes belong in the description file's Implementation Notes section. backlog-archive.md was abolished in v1.19.1 — completed and cancelled task records live in documentation/archive/, not in a rolling file that agents read on every invocation.
Path resolution
The skill defines a three-step path resolution rule. First, check whether datarim/ exists in the current working directory. If not, walk up the directory tree until a parent containing it is found. If no such directory exists, stop and run /dr-init. This rule prevents agents from creating stray datarim/ directories in the wrong location.
Since v1.17.0, the default install uses symlinks. The runtime path at $HOME/.claude/skills/{name}.md and the corresponding file in the cloned framework repository share the same inode. An edit to either path is the entire change — no copy or sync step exists. The skill documents how to detect copy-mode versus symlink-mode using stat to compare inode numbers.
Skill loading order and the blocklist
Skills load from two layers. The framework layer at $HOME/.claude/ resolves to the cloned repository in symlink-mode. A local overlay at $HOME/.claude/local/ allows user-private additions; when a name collides, the local overlay wins. Six critical skills cannot be shadowed from the local overlay: security, security-baseline, compliance, datarim-system, ai-quality, and evolution. Attempting to override any of these via local/skills/ causes validate.sh to exit 1.
The large-plan read strategy
When an L3+ task's plan, PRD, and supporting research documents together exceed roughly 600 lines, the skill recommends a single external-context delegation rather than sequential reads of every artefact. The structured summary from that delegation then drives implementation order, file paths, and verification criteria across /dr-do, /dr-qa, and /dr-compliance — re-reading the raw artefacts for each stage would introduce drift between the implementation summary and the verification summary.
The skill also fragments itself into sub-files — path-and-storage.md, task-identity-and-context.md, backlog-and-routing.md, and others — so commands load only the fragment relevant to the current sub-problem instead of the full system rules document.
See what Datarim is for the full pipeline context, or the datarim-doctor skill post for the migration algorithm that enforces this schema.