add-skill
Create new joelclaw skills with the idiomatic process — repo-canonical, symlinked, git-tracked, slogged. Triggers on 'add a skill', 'create skill', 'new skill', 'canonical skill', 'make a skill for', or any request to formalize a process or domain into a reusable skill.
88
83%
Does it follow best practices?
Impact
100%
2.70xAverage score across 3 eval scenarios
Passed
No known issues
Quality
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 solid description with excellent trigger terms and completeness, clearly stating both what the skill does and when to use it. Its main weakness is that the capability description relies on jargon ('repo-canonical, symlinked, git-tracked, slogged') rather than spelling out concrete actions, which slightly reduces specificity for someone unfamiliar with the workflow.
Suggestions
Replace or supplement jargon terms ('repo-canonical, symlinked, git-tracked, slogged') with concrete action descriptions, e.g., 'creates the skill file in the canonical repo location, sets up symlinks, adds git tracking, and logs creation in the slog'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (creating joelclaw skills) and mentions some properties ('repo-canonical, symlinked, git-tracked, slogged'), but these are jargon-heavy descriptors rather than concrete actions. The actual steps or actions involved in skill creation are not enumerated. | 2 / 3 |
Completeness | Clearly answers both 'what' (create new joelclaw skills with the idiomatic process) and 'when' (explicit 'Triggers on...' clause with multiple trigger phrases and a broader catch-all condition). | 3 / 3 |
Trigger Term Quality | Excellent explicit trigger terms listed: 'add a skill', 'create skill', 'new skill', 'canonical skill', 'make a skill for', plus the broader 'formalize a process or domain into a reusable skill'. These are natural phrases a user would say. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — it's specifically about creating 'joelclaw skills' with a particular workflow. The trigger terms are narrowly scoped to skill creation requests, making conflicts with other skills very unlikely. | 3 / 3 |
Total | 11 / 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 solid, actionable skill with clear step-by-step workflows and executable commands throughout. Its main weakness is moderate verbosity — some explanatory text could be trimmed, and the inline SKILL.md template adds bulk that might be better as a referenced template file. The Key Rules section is excellent, containing critical gotchas (symlink write-through, name mismatch warnings, reload behavior) that genuinely add non-obvious knowledge.
Suggestions
Trim the opening sentence ('Skills are modular instruction sets...') — Claude already knows what skills are; jump straight to the process.
Consider extracting the SKILL.md template into a separate template file (e.g., references/template.md) and referencing it, reducing the main skill's token footprint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but includes some unnecessary explanation (e.g., 'Skills are modular instruction sets that extend agent capabilities with specialized knowledge, workflows, or tool integrations' is something Claude already knows). The SKILL.md template section is somewhat verbose with inline comments that could be tighter. However, most content earns its place. | 2 / 3 |
Actionability | Fully executable bash commands for every step (mkdir, ln -sf, slog, git add/commit), concrete file paths, exact directory structures, and a complete SKILL.md template with frontmatter. Everything is copy-paste ready with clear placeholders. | 3 / 3 |
Workflow Clarity | Clear 6-step numbered sequence covering creation through commit. Includes an 'Updating Existing Skills' section as a separate workflow. The Key Rules section serves as validation guidance (e.g., name must match directory, never copy skills, symlink behavior). The workflow is well-sequenced with no ambiguity. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections, but it's somewhat monolithic — the full SKILL.md template, directory structures, Codex metadata, and rules are all inline. The optional references directory structure hints at progressive disclosure but the skill itself doesn't reference any external files for deeper content. | 2 / 3 |
Total | 10 / 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 |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- joelhooks/joelclaw
- Commit
825972c
- Reviewed
Table of Contents
Is this your skill?
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.