spec-loop-write-glossary

Create or update a project glossary in the Spec Loop AsciiDoc glossary format. Use when the user, project instructions, or `spec-loop-plan-task` already requires project glossary work. This skill is mandatory for AsciiDoc project glossaries unless the user explicitly opts out for the current project or session.

Quality

62%

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 ./skills/spec-loop-write-glossary/SKILL.md

Quality

Content

50%

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

The body is a lean, well-intentioned overview that defers detail to a referenced file, but it duplicates the description, lacks validation steps, and—critically—points to a glossary-format.md file that is not present in the bundle.

Suggestions

Provide the missing glossary-format.md (under references/ or alongside SKILL.md) so the core reference resolves.

Remove the two opening sentences that restate the frontmatter description to tighten conciseness.

Add an explicit validation step (e.g. confirm every glossary term is referenced and the AsciiDoc renders) before declaring glossary work complete.

Dimension	Reasoning	Score
Conciseness	The body is short and avoids explaining concepts Claude already knows, but the first two sentences ("Use for creating or updating a project glossary..." and "This skill is mandatory...") near-verbatim duplicate the frontmatter description, so not every token earns its place.	2 / 3
Actionability	Guidance is a concrete pointer ("read glossary-format.md and apply it", "Read and apply project instructions such as AGENTS.md"), but the actionable format detail is entirely deferred to a referenced file, so the body itself gives incomplete executable guidance.	2 / 3
Workflow Clarity	The simple read-then-apply sequence is present and unambiguous, but for AsciiDoc document manipulation there is no validation/verification step, which caps workflow clarity at 2 per the feedback-loops guidance.	2 / 3
Progressive Disclosure	The body correctly signals a one-level-deep reference to glossary-format.md, but no bundle directory exists and glossary-format.md is absent, so the referenced path is broken and navigation does not actually work.	2 / 3
	Total	8 / 12 Passed

Description

75%

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 clearly answers both what and when with a distinct, well-scoped niche, but its action list is thin and its trigger terms rely on internal workflow jargon rather than natural user language.

Suggestions

Add a couple of concrete sub-actions (e.g. add terms, resolve conflicts, validate cross-references) to lift specificity.

Soften the trigger to include natural user phrasings like "define project terms" or "build a glossary" rather than only referencing spec-loop-plan-task.

Dimension	Reasoning	Score
Specificity	It names the domain ("project glossary in the Spec Loop AsciiDoc glossary format") and the actions "Create or update", but offers only one task framed two ways rather than the multiple distinct concrete actions the level-3 anchor requires.	2 / 3
Completeness	It explicitly states what it does ("Create or update a project glossary...") and when to use it ("Use when the user, project instructions, or `spec-loop-plan-task` already requires project glossary work"), satisfying both halves.	3 / 3
Trigger Term Quality	"project glossary" and "glossary" are natural terms, but the trigger leans on workflow jargon ("spec-loop-plan-task already requires project glossary work") and misses common phrasings a user would naturally say.	2 / 3
Distinctiveness Conflict Risk	The narrow "Spec Loop AsciiDoc glossary format" niche with explicit scope limits ("mandatory for AsciiDoc project glossaries unless...opt out") makes it clearly distinguishable and unlikely to trigger for the wrong skill.	3 / 3
	Total	10 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: dpolivaev/spec-loop
Path: skills/spec-loop-write-glossary/SKILL.md
Commit: 741f932

Reviewed: 4 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.