Content
100%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.
An exemplary SKILL.md body: dense with project-specific gotchas that Claude could not infer, fully executable commands, and a clearly sequenced workflow with validation at every stage. External conventions are properly delegated to one-level-deep AGENTS.md references instead of being duplicated inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every sentence encodes non-obvious repo-specific knowledge — the mise-pinned turbo warning, why `build` must be in the gate list (`test:unit` depends on `^build`), the `Bin` line escape-sequence gotcha, the oxfmt-not-prettier rule — with no padding and no explanation of concepts Claude already knows. | 5 / 5 |
Actionability | Guidance is fully executable: the exact `turbo run build test:unit lint:tsc lint:eslint --filter ...` gate command, the `mise x -- yarn exec turbo run build --filter @apps/petrinaut-docs` invocation, and a copy-paste-ready jq/`gh pr checks` wait loop, plus concrete per-situation branches (structure change, arch-docs, Python packages). | 5 / 5 |
Workflow Clarity | The process is clearly sequenced (gates → changesets → docs sync → pre-PR hygiene → draft/CI/ready) with explicit validation checkpoints: gates re-run 'after every increment', the bounded wait loop that keeps waiting on empty or failed check output, pre-push `git diff --stat` hygiene review, and 'flip to ready only when checks are green' with AI-reviewer triage. | 5 / 5 |
Progressive Disclosure | Standing conventions are delegated one level deep to clearly signaled external files (`libs/@hashintel/petrinaut/AGENTS.md`, `apps/petrinaut-opt/AGENTS.md`) with named sections rather than inlined, the PR template is linked, and the ~55-line body stays a lean overview — no bundle files exist, so the body itself is the appropriate structure. | 5 / 5 |
Total | 20 / 20 Passed |