Use when creating or modifying Justfiles in this repository, when adding new recipes, or when organizing just commands
60
49%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.opencode/skills/writing-justfiles/SKILL.mdQuality
Discovery
22%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 description is incomplete and inverted - it only specifies when to use the skill without explaining what the skill actually does. The lack of concrete capabilities (what operations can be performed on Justfiles) makes it difficult for Claude to understand the skill's value proposition. While it mentions domain-specific terms like 'Justfiles' and 'recipes', the description needs substantial improvement to be useful for skill selection.
Suggestions
Add a 'what' clause describing specific capabilities, e.g., 'Creates and maintains Justfiles with properly formatted recipes, variables, and dependencies.'
Expand trigger terms to include variations like 'justfile', 'just task', 'command runner', 'build recipes', '.just'
Restructure to lead with capabilities before the 'Use when' clause, following the pattern: '[What it does]. Use when [triggers].'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'creating or modifying' and 'organizing' without specifying concrete actions. It doesn't explain what specific operations can be performed on Justfiles (e.g., adding build targets, defining variables, setting up dependencies). | 1 / 3 |
Completeness | The description only addresses 'when' to use the skill but completely omits 'what' the skill actually does. There's no explanation of capabilities - only trigger conditions are provided. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords 'Justfiles', 'recipes', and 'just commands' that users might say, but misses common variations like 'justfile', 'just task', 'just runner', 'command runner', or '.just' files. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Justfiles' and 'recipes' provides some distinctiveness from generic file editing skills, but 'organizing commands' is vague enough to potentially overlap with shell scripting or Makefile skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, actionable skill with excellent concrete examples and clear workflow guidance for writing Justfiles. The content provides copy-paste ready patterns and good error prevention through the Common Mistakes table. However, it could be more concise by trimming explanations of basic concepts and could benefit from splitting some detailed sections into separate reference files.
Suggestions
Remove or significantly shorten the 'Why export' and 'Why these options' explanations - Claude understands these shell and variable concepts
Consider moving 'Integration with BuildStream' and 'Common Patterns' sections to separate reference files, keeping SKILL.md as a leaner overview with links
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient but includes some redundancy - the 'Why export' and 'Why these options' explanations cover concepts Claude likely knows. The tables and examples are well-structured but some sections could be tightened. | 2 / 3 |
Actionability | Excellent actionability with fully executable code examples, copy-paste ready patterns, clear ✅/❌ comparisons, and concrete Justfile syntax throughout. The real-world example at the end ties everything together. | 3 / 3 |
Workflow Clarity | Clear workflow guidance with explicit ordering principles ('order by logical workflow, not alphabetically'), validation patterns (file existence checks, conditional execution), and composition patterns. The 'Common Mistakes' table provides a clear checklist. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections and a quick reference table, but it's a monolithic document that could benefit from splitting detailed patterns (BuildStream integration, common patterns) into separate reference files for a cleaner overview. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
f062bf8
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.