Skip to content

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

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

Activity

  1. added a commit that references this issue on Apr 8, 2026
    d0acc77
  2. added a commit that references this issue on Apr 12, 2026
    b011e99
  3. added
    area:coreMOS 编排层 / 框架底座 / 跨模块问题
    ai:taskDispatched to AI coding agent | 已派发给 AI 编码任务
    on May 26, 2026
  4. added
    area:memory记忆存储、检索、更新、召回逻辑
    and removed
    types:enhancementNew feature or improvement | 新功能或改进
    ai:taskDispatched to AI coding agent | 已派发给 AI 编码任务
    area:coreMOS 编排层 / 框架底座 / 跨模块问题
    on Jul 7, 2026
  5. added
    status:readyReady for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发
    on Jul 8, 2026
  6. added
    status:in-progressSomeone or AI is working on it | 人工或 AI 正在处理
    and removed
    status:readyReady for implementation; waiting for assignee or AI dispatch | 可进入实现,等待认领或派发
    on Jul 13, 2026
  7. Memtensor-AI commented on Jul 26, 2026

    @Memtensor-AI
    Collaborator

    Fixed by #2100 (align generated skill guidance with skill-creator practices), merged into dev-v2.0.25 and released to main via #2156 (v2.0.25). Closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:memory记忆存储、检索、更新、召回逻辑status:in-progressSomeone or AI is working on it | 人工或 AI 正在处理

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions