generate-agent-skills

Architects, generates, and validates Agent Skills. Enforces specification and best practices. Used any time an agent skill must be created or updated.

Quality

57%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.github/skills/generate-agent-skills/SKILL.md

Quality

Discovery

67%

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 adequately communicates its purpose and includes an explicit 'when to use' clause, which is a strength. However, the actions described are somewhat abstract ('architects', 'enforces specification') rather than concretely specific, and the trigger terms could be expanded to cover more natural user phrasings. It would benefit from more concrete capability details and additional keyword variations.

Suggestions

Add more concrete actions such as 'creates skill.md files', 'generates YAML frontmatter', 'validates required fields and structure' to improve specificity.

Expand trigger terms to include natural variations like 'skill file', 'skill.md', 'new skill', 'write a skill', 'skill template' to improve discoverability.

Dimension	Reasoning	Score
Specificity	Names the domain ('Agent Skills') and lists some actions ('architects, generates, validates, enforces specification and best practices'), but these actions are somewhat abstract—'architects' and 'enforces specification' are vague compared to truly concrete actions like 'creates YAML frontmatter' or 'validates required fields'.	2 / 3
Completeness	Clearly answers both 'what' (architects, generates, validates agent skills; enforces specification and best practices) and 'when' ('any time an agent skill must be created or updated'), with an explicit trigger clause.	3 / 3
Trigger Term Quality	Includes 'agent skill', 'created', and 'updated' as relevant keywords, but misses common natural variations users might say such as 'skill file', 'skill.md', 'new skill', 'write a skill', 'skill template', or 'skill definition'.	2 / 3
Distinctiveness Conflict Risk	The term 'Agent Skills' provides some specificity, but 'architects, generates, and validates' could overlap with general code generation or scaffolding skills. The description doesn't mention unique file formats or structures that would clearly distinguish it.	2 / 3
	Total	9 / 12 Passed

Implementation

47%

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

This skill has excellent workflow clarity with a well-defined 6-step process, explicit validation gates, and error recovery paths. However, it is severely undermined by verbosity — redundant warnings, repeated stop conditions, and explanatory content that Claude doesn't need inflate the token cost significantly. The content would benefit from aggressive trimming and moving detailed guidance into the referenced files it already points to.

Suggestions

Remove the redundant 'CRITICAL WORKFLOW REQUIREMENTS' section at the top — the mandatory nature of Steps 3 and 5 is already conveyed within those steps via warnings and stop conditions.

Move the resource type descriptions (scripts/, references/, assets/ with their ✅/❌ lists) and the 'Script vs. Checklist' decision framework to `references/BEST_PRACTICES.md` and reference it with a single line.

Move the 'Common Iteration Patterns' problem/solution table in Step 6 to a reference file, keeping only a brief 'test → fix → re-validate' loop in the main body.

Add a concrete, complete example of a finished SKILL.md frontmatter + body snippet (not just descriptions of what to write) to improve actionability in Step 4.

Dimension	Reasoning	Score
Conciseness	Extremely verbose with excessive repetition of warnings, stop conditions, and emoji-laden emphasis. The 'CRITICAL WORKFLOW REQUIREMENTS' section repeats information found in Steps 3 and 5. Checklists, verification checkpoints, and stop conditions are redundantly stated multiple times. Much of the content (e.g., explaining what scripts/references/assets are, example clarifying questions) explains concepts Claude already understands.	1 / 3
Actionability	Provides concrete executable commands like `python3 scripts/scaffold_skill.py --name <skill-name>` and `python3 scripts/validate_skill.py --path <path>`, plus specific file paths and expected outputs. However, much guidance remains descriptive rather than executable (e.g., 'Write SKILL.md Content' is largely advisory prose rather than concrete templates or copy-paste examples of actual skill content).	2 / 3
Workflow Clarity	The 6-step workflow is clearly sequenced with explicit validation checkpoints at Steps 3 and 5, stop conditions that prevent proceeding on failure, a post-validation checklist, and a feedback loop in Step 6 (test → identify friction → iterate → re-validate). Error recovery paths are specified for each validation step.	3 / 3
Progressive Disclosure	References to external files like `references/BEST_PRACTICES.md`, `references/SPECIFICATION.md`, `references/workflows.md`, and `references/output-patterns.md` are well-signaled and one level deep. However, the SKILL.md itself is monolithic and overly long — significant content (resource type descriptions, design patterns, common iteration patterns) could be moved to reference files. No bundle files were provided to verify referenced paths exist.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: canonical/copilot-collections
Commit: c5644f6

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.