skill-issues

Track project blockers, bugs, and gaps across sessions — use when issues pile up or need triage

Quality

58%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-issues/SKILL.md

Quality

Content

50%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is well-organized and highly actionable, with concrete bash commands, formats, and error paths for every subcommand. Its weaknesses are substantial redundancy (the same flows repeated in Quick Reference, Common Patterns, and Best Practices sections) and a destructive file-rewrite step lacking a verification checkpoint, plus a non-portable `sed -i ''`.

Suggestions

Cut the redundant "Quick Reference", "Common Patterns", and "The Bottom Line" sections, which restate the Subcommands flows, roughly halving the file.

Add a verification step after each ISSUES.md write, e.g. re-read the file and confirm the pre-existing row count is unchanged before confirming success.

Replace `sed -i ''` with a portable invocation (e.g. `sed -i.bak ... && rm -f .octo/ISSUES.md.bak`) so the initialize flow works on Linux as well as macOS.

Dimension	Reasoning	Score
Conciseness	The body restates the same information several times: "Quick Reference", "Common Patterns", "The Bottom Line", and "Severity Levels" duplicate the Subcommands flows and the AskUserQuestion option descriptions. This matches anchor 2 ('noticeably verbose; several unnecessary... padded sections') — it does not teach basics Claude already knows, so it stays above anchor 1.	2 / 5
Actionability	Provides mostly executable guidance: a complete ID-generation bash script, grep-based existence checks, exact table formats, error messages, and a full AskUserQuestion payload. Falls short of anchor 5 because `sed -i ''` is macOS-only and the file-modification step is comment-only pseudocode ("# Modify specific section only").	4 / 5
Workflow Clarity	Each subcommand has a clear numbered sequence and not-found error paths, but the destructive whole-file rewrite of ISSUES.md has no post-write verification checkpoint (e.g., confirm all pre-existing rows survived). Per the rubric's cap for destructive/batch operations without validation, this holds at anchor 3 rather than 4.	3 / 5
Progressive Disclosure	The single 490-line file is well-sectioned, but large chunks (the ID generation algorithm, Best Practices, and Integration with Other Skills) are inlined rather than split into reference files or trimmed, and no references exist. This fits anchor 3 ('content that should be separate is inline') despite good structure.	3 / 5
	Total	12 / 20 Passed

Description

66%Weight 40%Scale 1-5

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 and answers both what and when with natural trigger keywords like "issues" and "blockers". Its main weaknesses are under-selling the skill's concrete capabilities (only "track" is named) and unstated boundaries against GitHub/git issue tooling that could cause mis-triggering.

Suggestions

Name the concrete subcommands in the description, e.g. "Track, triage, resolve, and review project blockers, bugs, and gaps across sessions".

Add a disambiguating clause such as "for local project issue files, not GitHub/git issues" to reduce conflict with gh CLI and git skills.

Include a broader synonym like "problems" among the trigger terms to catch more natural phrasings.

Dimension	Reasoning	Score
Specificity	"Track project blockers, bugs, and gaps" names the domain but only the single action "track" (triage is only implied), omitting the skill's actual capabilities (add, resolve, show). This matches anchor 3 ('1-2 concrete actions, but not comprehensive') rather than 4 ('several specific actions').	3 / 5
Completeness	Both halves are explicit: what ("Track project blockers, bugs, and gaps across sessions") and when ("use when issues pile up or need triage"). It falls short of anchor 5 because the when-clause lacks concrete user-mention trigger phrases, but exceeds anchor 3 since both what and when are clearly stated.	4 / 5
Trigger Term Quality	Includes natural user terms — "issues", "blockers", "bugs", "triage", "track" — giving good keyword coverage, though common synonyms like "problems" or "defects" are missing, keeping it below the comprehensive anchor 5.	4 / 5
Distinctiveness Conflict Risk	"bugs" and "issues" risk overlap with GitHub issue management, git commands, and todo/debugging skills, and the description does not state the exclusions (those live in the body), fitting anchor 3 ('could still overlap with similar skills').	3 / 5
	Total	14 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (512 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-issues/SKILL.md
Commit: 0093dab

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.