Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The content is a lean, project-specific policy document with genuinely executable commands and explicit validation gates, scoring consistently at 4 across all dimensions. It falls short of 5 mainly through mild redundancy of governance rules, an unnumbered workflow with only implied error-recovery, and inline policy density that would benefit from a reference file.
Suggestions
Consolidate the facts-authoring guardrail (currently stated three different ways across sections 1–2) into a single 'Do not author facts locally' rule to save tokens.
Number the update workflow steps and annotate each command — e.g., note what '--bundle --check' gates and which command to re-run when a check fails — to make the feedback loop explicit.
Move the 'Discovery, execution and recovery' policy detail into a reference file (e.g., references/discovery.md) and keep SKILL.md as a shorter overview with a clearly signaled link.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body contains no padding or explanation of concepts Claude already knows — every line is project-specific policy ('Unknown prices/estimates remain unknown, never zero'). However, the facts-authoring guardrail is restated three ways ('Do not recreate an authored factual catalogue or GG allowlist in Grida', 'It is not a second facts authoring home', 'Source corrections belong in the public Models project, not local overrides'), which is minor redundancy that could be trimmed — anchor 4 rather than 5. | 4 / 5 |
Actionability | A copy-paste-ready command block ('node scripts/ai-catalogue/generate.mjs --bundle --check', 'pnpm --filter @grida/ai test', 'cargo test -p grida-ai --locked') plus concrete paths and identifiers ('data/ai/presets.json', 'catalog.snapshot.legacy()', 'GRIDA-SEC-006') provide mostly executable guidance. Sections 1 and 3 are guardrail prose rather than steps, and the commands are unannotated (no note on what each gates or when to re-run), keeping it at anchor 4. | 4 / 5 |
Workflow Clarity | The update workflow has a clear sequence — read data/ai/README.md, inspect the full old/new released diff, then generate → build → bundle → '--bundle --check' → test → typecheck → cargo test — with real validation checkpoints ('review intentional fixture changes rather than regenerating a baseline to hide drift'). Steps are unnumbered, the command block is a flat list, and error-recovery is implied rather than an explicit feedback loop, so it matches anchor 4 rather than 5. | 4 / 5 |
Progressive Disclosure | Three well-organized sections, an ownership table that doubles as a navigation map, and clearly signaled one-level-deep references to data/ai/README.md and hosted-ai.md. There are no bundle reference files (scripts/ holds only an unreferenced pointer file), and the dense policy in 'Discovery, execution and recovery' (~30 lines of inline rules) is content that could live in a separate reference — anchor 4's 'minor organization gaps'. | 4 / 5 |
Total | 16 / 20 Passed |