analyze-issue
Analyze a GitHub issue and create a detailed technical specification
51
41%
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 ./plugins/git/skills/analyze-issue/SKILL.mdQuality
Discovery
32%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 is concise but underdeveloped. It identifies the core workflow (GitHub issue → technical specification) but lacks specific sub-actions, explicit trigger guidance ('Use when...'), and natural keyword variations that would help Claude reliably select this skill from a large pool.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to turn a GitHub issue into a spec, plan implementation for an issue, or create a design document from a bug report or feature request.'
Expand the 'what' with concrete sub-actions, e.g., 'Parses issue requirements, identifies acceptance criteria, outlines architecture decisions, and produces a structured technical specification.'
Include natural keyword variations users might say: 'spec', 'tech spec', 'implementation plan', 'design doc', 'issue breakdown', 'feature request'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (GitHub issues, technical specifications) and describes two actions (analyze and create), but lacks detail on what 'analyze' entails or what the specification includes. | 2 / 3 |
Completeness | Describes what the skill does at a high level but completely lacks a 'Use when...' clause or any explicit trigger guidance, which per the rubric caps completeness at 2, and the 'what' itself is also thin, warranting a 1. | 1 / 3 |
Trigger Term Quality | Includes natural terms like 'GitHub issue' and 'technical specification', but misses common variations users might say such as 'spec', 'tech spec', 'issue breakdown', 'implementation plan', or 'design doc'. | 2 / 3 |
Distinctiveness Conflict Risk | Somewhat specific to GitHub issues and technical specs, but could overlap with general planning, project management, or code review skills since 'analyze an issue' and 'create a specification' are broad activities. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable template-driven workflow for creating technical specifications from GitHub issues, with clear file naming conventions and output format. Its main weaknesses are vague intermediate steps (steps 3-4), lack of concrete commands for fetching issues, missing validation/error handling checkpoints, and a somewhat verbose inline template that could be externalized. The skill would benefit from more executable specificity and explicit validation steps.
Suggestions
Replace vague steps like 'Understand the requirements thoroughly' and 'Review related code and project structure' with concrete actions (e.g., 'List files matching keywords from the issue title', 'Search codebase for related functions/classes')
Add explicit validation checkpoints: verify the issue exists before proceeding, confirm the spec covers all issue requirements before saving
Include the actual command for fetching GitHub issues (e.g., `gh issue view $NUMBER`) rather than delegating entirely to load-issues.md, or provide the essential content inline
Consider extracting the spec template into a separate template file and referencing it, reducing the SKILL.md body length
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately verbose. The template sections are useful but some are overly prescriptive for Claude (e.g., explaining what labels and priority mean). The step-by-step instructions are reasonable but could be tighter. The confirmation summary instructions at the end add some unnecessary hand-holding. | 2 / 3 |
Actionability | The skill provides a clear template structure and file naming conventions, which is concrete. However, it lacks executable code/commands (no actual GitHub CLI commands for fetching issues), and step 2 delegates to another file (`load-issues.md`) without providing the actual method. Steps 3-4 ('Understand the requirements thoroughly', 'Review related code') are vague. | 2 / 3 |
Workflow Clarity | Steps are listed in sequence (check existing → fetch → analyze → create spec → save), which is good. However, there are no validation checkpoints — no step to verify the fetched issue is correct, no validation that the spec is complete before saving, and no error recovery if the issue doesn't exist or the fetch fails. | 2 / 3 |
Progressive Disclosure | The skill references `./claude/commands/load-issues.md` for issue fetching details, which is a reasonable one-level-deep reference. However, no bundle files are provided to verify this reference exists, and the bulk of the content (the full template) is inline rather than being split into a separate template file, making the skill longer than necessary. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- NeoLabHQ/context-engineering-kit
- Commit
dedca19
- 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.