Skip to content

docs(skill-development): update validation checklist and clarify reference file purposes #41

@sjnims

Description

@sjnims

Summary

The skill-development SKILL.md has two content gaps compared to official Claude Code documentation:

  1. Validation checklist missing name/description format rules
  2. Reference file purposes not clearly explained

Problem 1: Incomplete Validation Checklist

The official docs specify format requirements that aren't in our validation checklist:

  • name: lowercase letters, numbers, and hyphens only (max 64 characters)
  • description: max 1024 characters

Current checklist (lines 175-199) only checks:

  • SKILL.md file exists with valid YAML frontmatter
  • Frontmatter has name and description fields
  • ❌ Missing: name format validation
  • ❌ Missing: description length check

Problem 2: Unclear Reference File Purposes

The "Additional Resources" section lists two reference files without explaining WHY both exist:

- **`references/skill-creation-workflow.md`** - Complete step-by-step skill creation process...
- **`references/skill-creator-original.md`** - Full original skill-creator methodology

Users don't know which to use or why there are two.

Proposed Solution

Fix 1: Update Validation Checklist

Add to Structure section:

**Structure:**
- [ ] SKILL.md file exists with valid YAML frontmatter
- [ ] Frontmatter has `name` and `description` fields
- [ ] Name uses only lowercase letters, numbers, and hyphens (max 64 chars)
- [ ] Description is under 1024 characters
- [ ] Markdown body is present and substantial
- [ ] Referenced files actually exist

Fix 2: Clarify Reference Descriptions

Update to:

### Reference Files

For detailed guidance, consult:

- **`references/skill-creation-workflow.md`** - Plugin-specific skill creation workflow (recommended for plugin skills)
- **`references/skill-creator-original.md`** - Original generic skill-creator methodology (includes init/packaging scripts for standalone skills)

Acceptance Criteria

  • Validation checklist includes name format rules (lowercase, hyphens, 64 char max)
  • Validation checklist includes description length limit (1024 chars)
  • Reference file descriptions explain the difference and when to use each
  • Changes are in SKILL.md only (no reference file changes needed)

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions