Content
57%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 body delivers a well-organized, largely executable overview of the instinct system with strong tables and copy-paste configuration, but it is diluted by changelog and advocacy content, lacks validation checkpoints in its setup workflow, and doesn't leverage progressive disclosure — everything is inline and bundle file references are incomplete (observe.sh missing). Scores cluster at 3-4, indicating a solid skill with clear tightening opportunities.
Suggestions
Move the version-history tables ("What's New in v2.1", "What's New in v2 (vs v1)"), the "Why Hooks vs Skills" rationale, and the Backward Compatibility section into a CHANGELOG.md or references/ file, keeping SKILL.md focused on current-state operation.
Add an explicit validation step to the Quick Start (e.g., "run /instinct-status or check projects/<hash>/observations.jsonl to confirm hooks are firing") so users can verify setup succeeded before moving on.
Fix bundle references: either ship hooks/observe.sh or correct the hook config path, link to the actual scripts (instinct-cli.py, detect-project.sh), and consider splitting the Scope Decision Guide and Confidence Scoring reference tables into references/ files with clear one-level-deep links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The operational core (Quick Start, Commands, Configuration, File Structure, Scope Guide, Confidence Scoring) is efficient and table-based, but it is padded with two version-history tables ("What's New in v2.1", "What's New in v2 (vs v1)"), a marketing-flavored "Why Hooks vs Skills" section ("Hooks fire 100% of the time, deterministically"), Backward Compatibility notes, and a closing tagline. The version-comparison tables are time-sensitive changelog content not placed in a deprecated/old-patterns section, which the guidelines penalize. This fits anchor 3 (mostly efficient, some unnecessary content that could be tightened) better than anchor 2, since the majority of the body is actionable operational reference rather than padding. | 3 / 5 |
Actionability | Mostly executable guidance: copy-paste JSON hook configs for both plugin and manual installs, a mkdir command, concrete promote invocations with flags ("python3 instinct-cli.py promote --dry-run"), a config.json example with a key table, and a full command table. It falls short of anchor 5 because the Quick Start's hook config points at "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh", which does not exist in the bundle, and the six slash commands have no defined file locations — gaps a user must resolve to actually run the system. | 4 / 5 |
Workflow Clarity | A sequence is present (numbered Quick Start: enable hooks -> initialize directories -> use commands) and the observe->analyze->instinct->evolve pipeline is diagrammed, but validation checkpoints are missing or implicit: there is no step to verify hooks fired or that observations.jsonl is being written after setup. Only promote offers a checkpoint (--dry-run), and evolve has no feedback loop. This matches anchor 3 (steps listed but validation gaps) better than anchor 4, whose example includes an explicit verify step. | 3 / 5 |
Progressive Disclosure | Section headers are clear and consistent, but everything is inlined in a single ~360-line SKILL.md with no references/ directory: version-history tables, the detailed file tree, the scope decision guide, and confidence-scoring reference material are all inline content that could be split out. Bundle references are not clearly signaled — "instinct-cli.py" and "observe.sh" are mentioned by name without links (and observe.sh is missing from the bundle while the existing scripts/detect-project.sh is never referenced). This fits anchor 3 (some structure, references present but not clearly signaled, content that should be separate is inline). | 3 / 5 |
Total | 13 / 20 Passed |