Content
77%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 is a thorough, executable engineering playbook with strong workflow sequencing and validation checkpoints, but it is monolithic: everything lives inline in SKILL.md with no bundled reference files to progressively disclose the catalog and per-source detail.
Suggestions
Move the Tier-1 source catalog table and the per-file posthog/code and posthog/posthog checklists into a references/ file (e.g. references/source-catalog.md and references/checklists.md), keeping SKILL.md a concise overview that links one level deep.
Provide a complete, copy-paste-ready emitter template (the full github_issues.py shape) in a reference file rather than instructing to 'copy github_issues.py and adapt', so the most failure-prone step is fully executable.
Tighten the OAuth/form-rendering section by consolidating the three overlapping explanations of DynamicSourceSetup into a single concise statement plus a reference link.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense and domain-specific, assuming Claude's knowledge of worktrees, migrations, and PRs without padding; the OAuth/form-rendering sections could be tightened slightly but every token earns its place with concrete file paths and gotchas. | 4 / 5 |
Actionability | Provides exact file paths, exact commands (`python manage.py makemigrations signals`), concrete switch-case routing, and a copy-paste worktree block; falls just short of 5 because the emitter step says to copy and adapt github_issues.py rather than giving complete code. | 4 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced across the posthog/posthog and posthog/code checklists with explicit deploy-ordering dependencies and dedicated 'Verify' checkpoints, including validation for the destructive migration step (`makemigrations --check`). | 5 / 5 |
Progressive Disclosure | No references/scripts/assets bundle exists, so all detail — the full Tier-1 catalog table and the per-source checklists — is inlined in one ~250-line file; cross-references to other skills exist, but content that could be offloaded to one-level-deep reference files is not split out. | 3 / 5 |
Total | 16 / 20 Passed |