CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

make-issue-spec

Create a markdown document that describes a specific task along with concise implementation plan, at issues/YYYYMMDD-blah-blah.md, where YYYYMMDD is based on today's date.

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/workflow/skills/make-issue-spec/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%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 appropriately brief for a simple skill, but it delegates almost everything to the description and offers no concrete structure, template, or example for the issue spec it asks Claude to produce. Actionability is the main weakness: Claude must invent the spec format from scratch.

Suggestions

Provide a concrete template or section list for the issue spec (e.g., Context, Task, Implementation plan, Open questions) so the output format is unambiguous.

Clarify the workflow order: ask clarifying questions before writing, then draft, then optionally confirm with the user before staging.

Replace the filler opening ('There isn't a lot more to this...') with a one-line statement of the deliverable, and make the git step concrete (e.g., 'git add the new file; commit only if the user approves').

DimensionReasoningScore

Conciseness

The body is ~5 lean lines with no concept explanations, but the opening "There isn't a lot more to this than what the top level description says" is filler that earns nothing. Not 5: that meta-sentence wastes tokens; not 3: the rest is efficient and assumes Claude's competence with no padding.

4 / 5

Actionability

Guidance is high-level: "a clear specification of what is needed", "ask the user any questions", "Stage this in Git if you have permissions" — there is no template, section structure, or example of what the issue spec should contain, and 'stage this in Git' gives no concrete command context. Not 3: there is no partially concrete, executable detail like a format or example; not 1: the directives (ask clarifying questions, stage in git, dated path) are at least specific intents.

2 / 5

Workflow Clarity

A rough process is implied (write the spec, ask questions about underspecified parts, stage in git), but the sequence is not laid out — whether to ask questions before or while writing is unclear — and there are no checkpoints such as confirming the spec with the user before staging. Not 4: the steps and their order are not clearly defined; not 2: the three directives do form a recognizable rough sequence.

3 / 5

Progressive Disclosure

The body is well under 50 lines with no bundle files and nothing inlined that belongs in a separate file, which suits a simple skill. Not 5: it is a single unstructured paragraph with no organizational structure, and the filler opening obscures what little overview there is.

4 / 5

Total

13

/

20

Passed

Description

50%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 states a clear 'what' with a concrete deliverable and path convention, but it entirely lacks a 'when' clause and natural trigger terms, capping completeness and trigger quality. It is serviceable but would not reliably surface when a user asks to write an issue or spec.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when the user asks to create an issue, task spec, or implementation plan document.'

Include natural trigger terms users would actually say: 'issue', 'spec', 'task description', 'implementation plan', 'write up a task'.

Replace the 'YYYYMMDD-blah-blah.md' placeholder with a cleaner example like 'issues/20261012-add-auth.md' to read as a concrete convention rather than jargon.

DimensionReasoningScore

Specificity

"Create a markdown document that describes a specific task along with concise implementation plan, at issues/YYYYMMDD-blah-blah.md" names the domain and 1-2 concrete actions (create a dated spec document with a task description and plan, follow the path convention), but coverage is not comprehensive — it never says what the spec should contain. Not 4: it does not list several distinct specific actions like the anchor example; not 2: the actions are more concrete than the purely generic 'Processes PDF files'.

3 / 5

Completeness

The 'what' is clear (create a dated markdown issue-spec document with a task description and implementation plan), but there is no 'Use when...' clause or any equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. Not 4: the 'when' is entirely absent, not merely imprecise.

3 / 5

Trigger Term Quality

Keywords like "markdown document", "specific task", and "implementation plan" are relevant, but the natural phrases a user would say ("issue", "spec", "write up a task", "ticket") are missing, and the odd "YYYYMMDD-blah-blah" placeholder reads as jargon rather than a trigger term. Not 4: no natural trigger-phrase coverage; not 2: terms are more domain-specific than 'Works with files'.

3 / 5

Distinctiveness Conflict Risk

"a markdown document that describes a specific task" could overlap with general documentation, planning, or writing skills, and no trigger phrases distinguish it. Not 4: the overlap with related skills is more than minor; not 2: the dated issues/ path convention gives it some niche identity.

3 / 5

Total

12

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

pchalasani/claude-code-tools

Path

plugins/workflow/skills/make-issue-spec/SKILL.md

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.