This skill should be used when the user says "bug spec", "arness code bug spec", "investigate this bug", "help me debug", "trace this bug", "diagnose this issue", "I found a bug", "something is broken", "why is X not working", "fix this bug", "debug this", "why is this not working", or wants to iteratively investigate a bug through guided conversation with diagnostic analysis. Bridges the gap between a bug report and either a direct fix or a structured bug specification for the Arness pipeline.
64
76%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/arn-code/skills/arn-code-bug-spec/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description excels at trigger term coverage and completeness, providing an extensive list of natural user phrases and clearly stating both what the skill does and when to use it. However, the actual capabilities could be more specifically enumerated (e.g., what diagnostic steps it performs, what the output spec looks like), and the broad debugging trigger terms create some conflict risk with general coding assistance skills.
Suggestions
Add more specific concrete actions the skill performs, such as 'analyzes stack traces, traces code paths, generates structured bug specification documents, proposes targeted fixes'
Consider narrowing some of the very generic trigger terms (like 'fix this bug' or 'debug this') or adding qualifying context to reduce overlap with general coding skills — e.g., 'Use for in-depth iterative bug investigation rather than quick one-off fixes'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions 'iteratively investigate a bug through guided conversation with diagnostic analysis' and 'bridges the gap between a bug report and either a direct fix or a structured bug specification,' which names the domain and some actions but doesn't list multiple concrete specific actions like tracing code paths, analyzing logs, or generating spec documents. | 2 / 3 |
Completeness | The description explicitly answers both 'what' (bridges gap between bug report and a fix or structured bug specification via guided conversation with diagnostic analysis) and 'when' (extensive list of trigger phrases plus the general condition of wanting to investigate a bug iteratively). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including 'bug spec', 'investigate this bug', 'help me debug', 'trace this bug', 'diagnose this issue', 'I found a bug', 'something is broken', 'why is X not working', 'fix this bug', 'debug this' — these are phrases users would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | While the 'bug spec' and 'Arness pipeline' terms are distinctive, many of the trigger phrases like 'fix this bug', 'debug this', 'why is this not working' are very generic debugging terms that could easily overlap with general coding assistance or other debugging skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured orchestration skill for a complex multi-agent bug investigation workflow. Its strengths are excellent workflow clarity with clear branching, convergence checks, and comprehensive error handling. Its main weakness is that several critical steps defer entirely to reference files, making the main skill body incomplete for actionability, and some agent invocation patterns are repeated verbosely across steps.
Suggestions
Inline the key decision criteria from diagnosis-flow.md (e.g., the six complexity questions) directly into Step 5 so the main skill is self-contained for the routing decision.
Consolidate the repeated agent invocation boilerplate (model lookup, Task tool, dispatch convention fallback) into a single 'Agent Dispatch' section referenced by all steps, rather than repeating it in Steps 3, 4, and 6B.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately verbose — it explains workflow routing logic and agent invocation patterns in detail that could be more concise. Some sections like Step 6B repeat context-passing patterns already established earlier. However, given the complexity of the multi-path workflow, most content earns its place. | 2 / 3 |
Actionability | The skill provides clear step sequences and specific file paths, but most of the concrete execution details are deferred to reference files (diagnosis-flow.md, bug-spec-template.md) rather than being inline. Steps 5, 6A, and parts of 6B essentially say 'read the reference file for the actual procedure,' making the main skill incomplete on its own. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced with numbered steps, explicit branching (simple vs complex path), iterative convergence checks in Step 4, validation via architect agent, and well-defined error handling with specific recovery actions. The feedback loops (diagnose → validate → converge) are explicit and the error handling section covers edge cases thoroughly. | 3 / 3 |
Progressive Disclosure | The skill provides a clear overview of the full workflow in the main body while appropriately deferring detailed procedures to well-signaled reference files (diagnosis-flow.md, bug-spec-template.md, agent-invocation-guide.md). References are one level deep and clearly listed in a dedicated References section. The main body gives enough context at each step to understand the flow without reading the references. | 3 / 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 | |
b9084b6
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.