Content
38%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 skill demonstrates broad domain knowledge with detailed illustrative code, but it fails on structure and efficiency: it is a 550-line monolith whose referenced bundle files don't exist, its code is non-executable pseudocode despite looking runnable, and it explains billing concepts Claude already knows. It needs to be split into the advertised reference files with a lean overview left in SKILL.md.
Suggestions
Create the advertised bundle files (references/billing-cycles.md, dunning-management.md, proration.md, tax-calculation.md, invoice-lifecycle.md, assets/billing-state-machine.yaml, invoice-template.html, dunning-policy.yaml) and move the inline class implementations into them, leaving SKILL.md as a lean overview — currently every listed reference is a dangling path.
Cut the 'Core Concepts' section and other background explanation (subscription states, common billing intervals, what proration is) — Claude already knows these; keep only non-obvious decisions like the chosen retry schedule and the no-refund seat-removal policy.
Make the code actionable or explicitly label it as illustrative: either provide runnable examples against a real library (e.g., stripe) with defined imports and helpers, or trim to the essential algorithmic snippets (proration formula, tiered pricing, dunning state transitions) and remove the undefined-boilerplate scaffolding.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~550-line body inlines seven full Python classes plus a 'Core Concepts' section explaining things Claude already knows ("Monthly (most common for SaaS)", a subscription state diagram, what proration is), and it duplicates material (dunning retry logic, invoice construction appears in two places). This matches anchor 2 ('noticeably verbose; several unnecessary explanations or padded sections'); it avoids 1 only because the domain-specific implementation details (retry schedules, proration formulas, tiered pricing) carry some non-obvious value. | 2 / 5 |
Actionability | The code is concrete and logically complete for the domain (proration math, tiered pricing, dunning schedules) but not executable: the Quick Start imports a fictional `billing` module, `stripe` is used without import, helpers like `generate_id`, `get_subscription`, `UsageRecord`, `send_email`, and `calculate_volume_pricing` are undefined, and `validate_vat_number`/`to_pdf` are `pass` stubs. This sits squarely on anchor 3 ('some concrete guidance but incomplete... missing key details') — above 2 because real, specific logic is present, below 4 because nothing runs as written. | 3 / 5 |
Workflow Clarity | A sequence exists in `process_billing_cycle` (check due → generate invoice → charge → mark paid or start dunning) and the dunning retry flow is ordered, but there are no validation checkpoints, no verify/retry loops for the charge-and-cancel operations, and no guidance for sequencing an actual implementation. Billing is a batch, financially destructive domain, so per the rubric's cap, missing validation holds this at anchor 3 ('sequence present but checkpoints missing or implicit'). | 3 / 5 |
Progressive Disclosure | The Resources section lists 8 bundle files (`references/billing-cycles.md` through `assets/dunning-policy.yaml`), but none of these files exist in the bundle — every referenced path is dangling — while the ~450 lines of implementation code those files should hold are inlined in SKILL.md itself. This matches anchor 2 ('content that clearly belongs in separate files is inlined'); it does not reach 3 because the references, though clearly signaled, are broken, and the body is effectively the monolithic pattern the rubric penalizes. | 2 / 5 |
Total | 10 / 20 Passed |