Content
82%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.
A strong, information-dense domain skill: every section is project-specific and actionable, with concrete commands, paths, and diagnostic tells rather than generic explanation. The main improvements are trimming the duplicated scope restatement and splitting the entrypoint inventory and deep diagnostics into reference files now that the body has grown past a single screen.
Suggestions
Conciseness: cut the opening paragraph and 'When to use' bullet list that restate the frontmatter description and the desktop-skill boundary verbatim — the description already carries that routing.
Progressive disclosure: move the Package Boundaries entrypoint inventory and the long Common Diagnostics prose (hydrate truncation, client-resolved tool-call hang) into reference files (e.g. references/diagnostics.md, references/entrypoints.md) and keep one-line summaries with links in SKILL.md.
Workflow clarity: add a short failure-handling loop to the Verification section — what to inspect or revert when typecheck/test fails and in what order to re-run the paired commands.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific knowledge (package seams, boundary tests, on-disk state locations) and assumes Claude's competence — no padding with known concepts — but the opening paragraphs restate the frontmatter description's scope and boundary hand-off, and several diagnostics paragraphs are wordy. This sits between the 4 anchor ('efficient; minor instances that could be trimmed') and 5 ('every token earns its place'), closer to 4 due to the duplicated scope restatement. | 4 / 5 |
Actionability | Guidance is fully executable: copy-paste verification commands ('pnpm --filter @grida/daemon typecheck && pnpm --filter @grida/daemon test', the read-only 'sqlite3 "file:$HOME/.grida/agent/sessions.db?mode=ro"' query), exact file paths for every subsystem, concrete constants (SCAN_MAX_FILES 10k, IGNORED_SCAN_DIRS, sse_query_token_paths), and diagnostic tells paired with named fix locations (workspaces/scan.ts, persistIncomingTail). It matches the 5 anchor — commands and examples cover the common cases without pseudocode. | 5 / 5 |
Workflow Clarity | Verification is sequenced per touched package with an explicit dependency checkpoint ('a change to @grida/daemon requires rebuilding it before @grida/agent typechecks') and escalation guidance to the desktop skill, and diagnostics give ordered symptom→cause→fix flows. It falls short of the 5 anchor because there is no explicit feedback loop for what to do when checks fail (fix→retry cycle), matching 'clear sequence with most checkpoints present; minor validation gaps' rather than 5's explicit error-recovery loops. | 4 / 5 |
Progressive Disclosure | Sections are well organized (Shape, Package Boundaries, Ownership Rules, Diagnostics, Live state, Security Boundary, Verification, Pointers) and the Pointers section gives one-level-deep, clearly labeled references to real repo files (READMEs, src paths, docs/wg/ai/agent/tool-design.md), with no nested references. It is not the 5 anchor because no bundle files (references/, scripts/, assets/) exist, and substantial inline material — the full entrypoint inventory and the long diagnostics prose — could live in separate reference files; this matches 'good structure; most content appropriately placed; minor organization gaps'. | 4 / 5 |
Total | 17 / 20 Passed |