-
Notifications
You must be signed in to change notification settings - Fork 715
[Enhancement] Skill generation template does not follow skill-creator best practices #1423
Description
Problem
The STEP1_SKILL_MD_PROMPT in src/skill/generator.ts lacks several important guidelines from the official skill-creator specification. This causes auto-generated skills to be non-standard and waste context window tokens.
Missing Guidelines
1. Frontmatter: name should be short
Current: No constraint on name length.
Expected: name MUST be 2-4 words in English kebab-case (e.g. "pdf-editor", not "how-to-edit-pdf-files-with-python").
2. Frontmatter: description must include trigger conditions
Current: The prompt doesn't emphasize that description is the primary trigger mechanism.
Expected: description should include BOTH what the skill does AND when to use it — with specific scenarios, keywords, and phrasings. The SKILL.md body is only loaded AFTER triggering, so "When to Use" sections in the body are useless to the agent.
3. Frontmatter: Only name and description fields
Current: No restriction on extra frontmatter fields.
Expected: ONLY name and description in frontmatter. No other fields.
4. Body: Progressive Disclosure for multi-variant skills
Current: No guidance on splitting content for skills that support multiple variants.
Expected: When a skill supports multiple frameworks/domains/options, keep ONLY the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate references/ files (e.g. references/aws.md, references/gcp.md). Reference them from SKILL.md.
5. Body: No extra documentation files
Current: No restriction on creating auxiliary files.
Expected: Do NOT create README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or any extra docs. Only SKILL.md + optional scripts/ references/ assets/.
6. Body: Assume Claude is smart
Current: No guidance on token efficiency.
Expected: Only include information Claude doesn't already have. Default assumption: Claude is already very smart.
Suggested Fix
Add these guidelines to STEP1_SKILL_MD_PROMPT in src/skill/generator.ts:
### Frontmatter rules (CRITICAL)
- name: MUST be short — 2-4 words in English kebab-case
- description: This is the PRIMARY trigger. Include BOTH what it does AND when to use it. List specific scenarios, keywords, and phrasings.
- ONLY name and description in frontmatter. No other fields.
### Body rules
- Keep SKILL.md body under 500 lines. Split large content into references/ files.
- Do NOT include "When to Use This Skill" section in body — it's already in description.
- Progressive Disclosure: For multi-variant skills, keep only core workflow in SKILL.md. Move variant-specific details to references/ files.
- Do NOT create README.md, CHANGELOG.md, or any extra docs.
- Only include information Claude doesn't already have.Impact
Without these guidelines, auto-generated skills:
- Have overly long
namefields that waste token space - Miss trigger conditions in
description, causing under-triggering - Include redundant "When to Use" sections in body that nobody reads
- Create unnecessary documentation files (README, CHANGELOG, etc.)
- Bloat the context window with verbose explanations Claude already knows