[meta-feedback] generate-skill (mixed)

[KyleAMathews]

Meta-Skill Feedback: generate-skill

Library: typography.js
Agent: claude-code
Artifact quality: good
Rating: mixed
Failure mode quality: good

What Worked

The generate-skill spec is thorough — section ordering (Setup, Core Patterns, Common Mistakes, References), the 500-line budget, the validation checklist, and the wrong/correct pair format for Common Mistakes all produce high-quality output. The distinction between core, sub-skill, and framework types is clear and practical. Reference file overflow guidance is well-designed.

What Failed

Descriptions are spec'd as "dense routing keys" packed with API keywords, but there's no mention of including natural-language trigger phrases like "Use when user asks...". The Claude Skills documentation identifies trigger phrases as critical for skill discovery — without them, skills may not load when users need them. No mention of the XML angle bracket restriction in YAML frontmatter (forbidden per Claude Skills standard — we had in a description). No guidance on cross-referencing between skills — skills should form a semi-lattice of "See also" pointers, not isolated trees. The scaffold should identify cross-cutting concerns during domain discovery and liberally sow cross-references throughout all generated skills. No testing guidance beyond structural validation — after generating skills, there should be a step to try real tasks and iterate.

Suggestions

Add to description guidance: "Include natural-language trigger phrases: 'Use when user asks [specific phrases]' alongside API keyword routing keys." Add to frontmatter rules: "No XML angle brackets (< >) in frontmatter — these appear in system prompts." Add cross-reference guidance: "Every concept that connects to another skill should have a 'See also: [skill] § [section]' pointer. Skills should form a semi-lattice, not isolated trees." Add a post-generation testing step: "Try 3-5 real tasks against your skills. Note where the AI struggles or needs info the skill doesn't provide. Use those gaps to iterate." Teach maintainers to start small — one basic skill, try tasks, iterate, expand — rather than generating a comprehensive set in one pass. The generate-skill spec says descriptions should be "dense routing keys" but the Claude Skills guide says focus on outcomes — descriptions need to serve double duty as routing key AND user-facing trigger signal.