skill-authoring-workflow

Turn raw PM content into a compliant, publish-ready skill. Use when creating or updating a repo skill without breaking standards.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/skill-authoring-workflow/SKILL.md

Quality

Content

75%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.

A well-structured workflow body with strong actionability, clear phased sequencing, and a validation phase plus Definition of Done checklist. It sits just below top marks because validation lacks an explicit fix-and-retry loop and a few commands use unfilled placeholders.

Suggestions

Add an explicit feedback loop in Phase 4 (e.g., 'If any check fails, fix the issue and re-run until all pass before commit') to push workflow clarity toward 5.

Trim occasional colloquial filler ('looks good to me' roulette, 'Shipping vibes, not standards') for a slightly leaner token footprint.

Fill or annotate the <skill-name>/<topic> placeholders in example commands so the common-case examples are fully copy-paste ready.

Dimension	Reasoning	Score
Conciseness	Mostly lean and well-organized into tight bullets and commands assuming Claude's competence; only minor flavor padding ('looks good to me' roulette, 'Shipping vibes, not standards') could be trimmed, fitting the 4 anchor rather than the fully stripped 5.	4 / 5
Actionability	Provides concrete, copy-paste-ready commands with flags across all phases (find-a-skill.sh, add-a-skill.sh, test-a-skill.sh, check-skill-metadata.py, zip-a-skill.sh); minor gaps via placeholders like <skill-name> and <topic> keep it just below the fully-covered 5.	4 / 5
Workflow Clarity	A clear six-phase sequence with an explicit Phase 4 validation block and a Definition of Done checklist; it lacks the explicit 'if validation fails, fix and re-run' feedback loop shown in the 5 anchor, capping it at 4.	4 / 5
Progressive Disclosure	Well-structured sections with a flat, one-level-deep References list and clearly signaled external script/doc references; no bundle files exist in this skill's directory, and the body content is appropriately inline rather than split, matching the 4 anchor with only minor organization gaps.	4 / 5
	Total	16 / 20 Passed

Description

70%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.

A solid, third-person description that answers both what and when with a clear trigger clause. It is held back from the top band by a single broad action verb and limited trigger-phrase variety rather than a comprehensive, multi-action capability list.

Suggestions

Expand specificity by listing 2-3 concrete actions the workflow performs (e.g., 'draft, tighten, and validate skills') instead of the single 'Turn ... into' verb.

Broaden trigger terms with natural synonyms users may say, such as 'author', 'build', or 'add a skill', to lift trigger-term coverage toward 5.

Add one more 'when' condition (e.g., 'or when preparing a skill for repo commit') to give the 'when' clause the variety of the 5 anchor.

Dimension	Reasoning	Score
Specificity	Names the domain ('raw PM content', 'repo skill') and one concrete action ('Turn ... into a compliant, publish-ready skill'), but stops short of listing multiple specific actions like the 4-5 anchors; not comprehensive enough to score above 3.	3 / 5
Completeness	Explicitly answers both what ('Turn raw PM content into a compliant, publish-ready skill') and when ('Use when creating or updating a repo skill without breaking standards'); the 'when' is a single concrete condition rather than the multiple varied trigger phrases of the 5 anchor, so 4 fits better than 5.	4 / 5
Trigger Term Quality	'Use when creating or updating a repo skill' gives good natural trigger coverage a user would actually say, though a few common synonyms ('author', 'build a skill', 'add a skill') are missing, keeping it just below 5.	4 / 5
Distinctiveness Conflict Risk	Skill authoring / standards compliance is a clear niche with low overlap risk; it is mostly distinct with only minor potential overlap with other meta-authoring skills, matching the 4 anchor rather than the fully-isolated 5.	4 / 5
	Total	15 / 20 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 suspicious	Warning
referenced_paths_exist	Referenced path issues: 15 missing	Warning

	Total	13 / 16 Passed

Repository: deanpeters/Product-Manager-Skills
Path: skills/skill-authoring-workflow/SKILL.md
Commit: a03af68

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