create-user-story

Create user stories with duplicate checking across any project tracker (Linear, GitHub Issues, Jira)

Quality

41%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/create-user-story/SKILL.md

Quality

Content

27%

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

This skill attempts to be comprehensive but suffers from extreme verbosity and poor content organization. It includes useful concrete details (specific MCP tool names, CLI commands, duplicate-checking workflow) but buries them in excessive explanation and repetitive tracker-specific sections that should be factored out. The monolithic structure makes it expensive in tokens and hard to navigate.

Suggestions

Reduce the skill to ~60-80 lines by extracting tracker-specific instructions (Linear, GitHub, Jira) into separate referenced files and keeping only the common workflow in SKILL.md.

Remove the user story template from inline content — either reference it as a separate template file or trust Claude to generate standard user story format with a one-line instruction.

Consolidate the three duplicate-checker agent prompts into a single parameterized pattern rather than spelling out nearly identical instructions three times.

Remove explanatory content Claude already knows (e.g., what acceptance criteria are, how to parse user input, what 'As a... I want... So that...' format is) and replace with terse directives.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~180+ lines. It over-explains concepts Claude already knows (how to parse user input, how to format markdown, what user stories are). The duplicate checker agent prompts are spelled out in full for three trackers with repetitive structure. The user story template, fallback table, and error handling sections add significant bulk that could be dramatically condensed.	1 / 3
Actionability	The skill provides concrete CLI commands for GitHub and specific MCP tool names for Linear, which is good. However, many sections use placeholder patterns like [CUSTOMIZE: your-org/your-repo] without clear resolution, the Jira instructions are vague ('use WebFetch or jira CLI'), and the agent task prompts are descriptive rather than truly executable. The workflow relies heavily on external files (MY-INTEGRATIONS.md, MY-PROFILE.md) whose structure is unspecified.	2 / 3
Workflow Clarity	The six-phase workflow is clearly sequenced and includes a critical validation checkpoint (duplicate check with user confirmation before creation, and story review before submission). However, the phases are overly elaborate and the feedback loops for error cases are listed in a table rather than integrated into the workflow steps. The parallel vs sequential agent mode branching adds complexity without clear validation at each branch.	2 / 3
Progressive Disclosure	The entire skill is a monolithic wall of text with no references to external files for detailed content. The user story template, all three tracker-specific instructions, agent prompts, fallback table, and error handling are all inline. This content would benefit enormously from splitting tracker-specific details, the story template, and agent prompts into separate referenced files.	1 / 3
	Total	6 / 12 Passed

Description

54%

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 identifies a clear niche (user story creation with duplicate checking across specific project trackers) and uses good natural trigger terms. However, it lacks an explicit 'Use when...' clause and could benefit from listing additional concrete actions beyond just creating user stories with duplicate checking.

Suggestions

Add a 'Use when...' clause, e.g., 'Use when the user wants to create tickets, user stories, or issues in Linear, GitHub Issues, or Jira, or needs to check for duplicate stories.'

Expand the list of concrete actions, e.g., 'Creates user stories, checks for duplicates across projects, and formats stories with acceptance criteria' to better convey the full scope of capabilities.

Dimension	Reasoning	Score
Specificity	Names a specific action ('Create user stories with duplicate checking') and lists target platforms, but only describes one core action rather than multiple concrete capabilities.	2 / 3
Completeness	Describes what the skill does but has no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric should cap completeness at 2, and the 'what' is also fairly thin — scoring at 1 since the 'when' is entirely missing.	1 / 3
Trigger Term Quality	Includes strong natural trigger terms users would say: 'user stories', 'Linear', 'GitHub Issues', 'Jira', 'project tracker', and 'duplicate checking' — good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	The combination of user story creation, duplicate checking, and specific project trackers (Linear, GitHub Issues, Jira) creates a clear niche that is unlikely to conflict with other skills.	3 / 3
	Total	9 / 12 Passed

Validation

90%

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 — 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: huytieu/COG-second-brain
Commit: 034af4c

Reviewed: about 1 month 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.