Extract an Allium specification from an existing codebase. Use when the user has existing code and wants to distil behaviour into a spec, reverse engineer a specification from implementation, generate a spec from code, turn implementation into a behavioural specification, or document what a codebase does in Allium terms.
80
76%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/allium/skills/distill/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-structured description with an explicit 'Use when...' clause and excellent trigger term variety covering multiple natural phrasings. Its main weakness is that the 'what' portion is somewhat thin—it describes a single high-level action rather than listing specific sub-capabilities. Overall it would perform well in skill selection due to its distinct niche and rich trigger coverage.
Suggestions
Add more specific sub-actions to the 'what' portion, e.g., 'Analyzes code structure, identifies behavioural contracts, and generates Allium spec files' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain ('Allium specification') and one core action ('Extract'), but doesn't list multiple concrete sub-actions like parsing, analyzing dependencies, generating specific spec sections, etc. It's a single action described at a high level. | 2 / 3 |
Completeness | Clearly answers both 'what' (extract an Allium specification from an existing codebase) and 'when' (explicit 'Use when...' clause with multiple trigger scenarios). The when clause is detailed and explicit. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms: 'distil behaviour into a spec', 'reverse engineer a specification from implementation', 'generate a spec from code', 'turn implementation into a behavioural specification', 'document what a codebase does'. These are varied phrasings a user would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | The 'Allium specification' domain is highly specific and niche, making it very unlikely to conflict with other skills. The triggers are clearly scoped to reverse-engineering specs from code in Allium terms. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent workflow structure and concrete code-to-spec examples that make the distillation process clear. However, it is significantly over-long and repetitive—multiple sections make the same abstraction-filtering point with different framings (Why test, Could it be different test, Product owner test, Template vs Instance test), and the concrete detail problem section exhaustively covers edge cases that could be in a reference file. The content would benefit greatly from aggressive condensation and splitting detailed examples into referenced files.
Suggestions
Consolidate the 'Why test', 'Could it be different test', 'Template vs Instance test', and 'Product owner' sections into a single concise abstraction-filtering section with one table, moving detailed examples to a reference file.
Move the 'Recognising library spec candidates' section (which is ~100 lines) to a separate reference file and summarize it in 5-10 lines in the main skill.
Move the 'Concrete detail problem' section with its Google OAuth, database, and third-party integration examples to a reference file like 'references/abstraction-judgments.md'.
Remove explanatory prose that restates what the examples already demonstrate (e.g., 'Code tells you how something works. A specification captures what it does and why it matters' — Claude knows this).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The document is extremely verbose at ~500+ lines. While the content is accurate, it extensively explains concepts Claude already understands (what abstraction means, means vs ends, strategy patterns, dependency injection). Many tables repeat the same point with slight variations (the 'Why test', 'Could it be different test', 'Product owner' test all make the same filtering judgment). The concrete detail problem section alone could be condensed by 70%. | 1 / 3 |
Actionability | The skill provides fully concrete, executable guidance with real Python code examples paired with their Allium spec equivalents. The extraction pattern tables (code pattern → spec pattern) are directly actionable, and the step-by-step distillation process with code-to-spec transformations gives Claude everything needed to perform the task. | 3 / 3 |
Workflow Clarity | The 7-step distillation process is clearly sequenced (Map territory → Extract entity states → Extract transitions → Find temporal triggers → Identify external boundaries → Abstract away implementation → Validate with stakeholders). Validation is explicitly included as Step 7, and the two checklists at the end serve as verification gates before finalizing. | 3 / 3 |
Progressive Disclosure | The document references external files (language-reference.md, worked-examples.md, patterns.md Pattern 8) which is good, but the main body itself is monolithic with enormous inline content that could be split. The scoping section, concrete detail problem section, and library spec candidates section are each substantial enough to warrant separate reference files, yet they're all inline. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (872 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
0f36ad4
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.