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 answering both what and when. Its main weakness is that the capability description relies on insider jargon ('repo-canonical, symlinked, git-tracked, slogged') rather than spelling out concrete steps in plain language, which slightly reduces specificity. Overall it would perform well in skill selection scenarios.
Suggestions
Replace jargon like 'repo-canonical, symlinked, git-tracked, slogged' with concrete action descriptions such as 'creates the skill file in the canonical repo location, symlinks it to the active skills directory, commits it to git, and logs the creation in the slog'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names the domain (creating joelclaw skills) and describes some qualities ('repo-canonical, symlinked, git-tracked, slogged'), but these are jargon-heavy descriptors rather than concrete actions. It doesn't list multiple distinct actions like 'create file, symlink to directory, register in git, log creation'. | 2 / 3 |
Completeness | Clearly answers both 'what' (create new joelclaw skills with the idiomatic process) and 'when' (explicit 'Triggers on...' clause listing specific phrases and a broader conceptual trigger). The when clause is explicit and detailed. | 3 / 3 |
Trigger Term Quality | Excellent trigger term coverage with natural phrases users would say: 'add a skill', 'create skill', 'new skill', 'canonical skill', 'make a skill for', plus the broader trigger of 'formalize a process or domain into a reusable skill'. These are highly natural and varied. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — it's specifically about creating 'joelclaw skills' with a particular idiomatic process. The trigger terms are narrowly scoped to skill creation requests, making it very unlikely to conflict with other skills. | 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 strong, actionable meta-skill for creating new skills. Its greatest strength is the fully concrete, copy-paste-ready workflow with explicit bash commands at every step. The key rules section effectively covers important gotchas (symlink destruction, name mismatches, reload requirements). Minor weaknesses include some verbosity in explanatory comments and all content being inline rather than leveraging progressive disclosure for optional/advanced sections.
Suggestions
Consider moving the Codex Desktop Metadata section and the detailed SKILL.md template into a references/ file to keep the main skill leaner and improve progressive disclosure.
Trim inline comments in the SKILL.md template (e.g., '# This shows in the skill list and is used for trigger matching') — the consuming agent can infer field purposes from context.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but includes some unnecessary guidance like 'Write for another Claude instance' explanations and the Codex Desktop Metadata section adds weight. The SKILL.md template section is somewhat verbose with inline comments explaining each field, though most of this is useful for a meta-skill about creating skills. | 2 / 3 |
Actionability | Every step has concrete, copy-paste-ready bash commands (mkdir, ln -sf, slog write, git add/commit). The SKILL.md template is fully specified with frontmatter structure and section headings. The directory structure is explicit with tree diagrams. | 3 / 3 |
Workflow Clarity | The 6-step process is clearly sequenced (create dir → write SKILL.md → add references → symlink → slog → commit) with each step numbered and containing exact commands. The Key Rules section serves as validation guidance, explicitly calling out the directory name/frontmatter mismatch issue and the destructive 'cat > symlink' anti-pattern. The updating workflow is also clearly documented. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections, but everything is inline in a single file. The optional references directory structure is shown but no bundle files exist to offload the SKILL.md template or detailed rules into. For a skill of this complexity (~100 lines of content), this is borderline acceptable but the Codex Desktop Metadata and detailed template could be split out. | 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
03f0a59
- 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.