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.
Highly actionable, project-grounded content with a complete template, exact commands, and a validation audit. The main gaps are minor redundancy (duplicated frontmatter, checklist restating rules) and a topic- rather than sequence-oriented presentation of the workflow.
Suggestions
Drop the duplicated frontmatter block from the 'Canonical template' (reference the 'Frontmatter' section) to tighten conciseness.
Add a short ordered 'workflow' list (write doc → set sourceId → use snippets → verify slug → run audit) to make the step sequence explicit alongside the checklist.
Consider moving the full canonical template into a references/ file and keeping only an annotated outline in SKILL.md to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and project-specific with no generic-concept padding ('the doc just renders what the API returns'), but the frontmatter block is duplicated verbatim in both the 'Frontmatter' and 'Canonical template' sections, and the checklist re-encapsulates earlier rules — minor trims that keep it below the lean top anchor. | 4 / 5 |
Actionability | Fully executable guidance: a complete canonical doc template, exact frontmatter fields, named shared snippets with purposes, the runnable audit command 'python manage.py audit_source_docs --docs-dir ../posthog.com/contents/docs/cdp/sources' with its failure conditions, and concrete exemplars (Stripe Option 1/Option 2, Postgres, ClickHouse). | 5 / 5 |
Workflow Clarity | All steps and checkpoints exist (template → sourceId match → snippets → slug agreement → audit → checklist) with a real validation gate (audit fails on missing files or bad sourceId, plus 301 redirect requirement), but the steps are organized by topic rather than an explicitly ordered sequence, so the reader assembles the order themselves. | 4 / 5 |
Progressive Disclosure | A well-organized single-file skill with clear section headers; the cross-references to /implementing-warehouse-sources and to posthog.com paths are clearly signaled and one level deep, and no bundle files exist to manage. It is above the ~50-line simple-skill threshold, and the full template/checklist could arguably live in a reference file, so it does not reach the top anchor. | 4 / 5 |
Total | 17 / 20 Passed |