Skip to content

[Enhancement] Skill generation template does not follow skill-creator best practices #1423

@prospect1314521

Description

@prospect1314521

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 name fields 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions