Skill Creator

A meta skill that helps you create new Claude Code skills using the agent-skill-npm-boilerplate template.

Instructions

When a user asks to create a skill, guide them through this systematic process:

Step 1: Create Project from Template

1. Guide them to use the GitHub template:

   • Visit https://github.com/RaoHai/agent-skill-npm-boilerplate
   • Click "Use this template" button
   • Or go directly to /generate

2. Or help them clone:

   git clone https://github.com/RaoHai/agent-skill-npm-boilerplate.git [skill-name]
   cd [skill-name]
   rm -rf .git
   git init
   

Step 2: Gather Requirements

Ask the user these essential questions:

About the Skill:

• What should the skill do? (Get clear description of purpose)
• When should it trigger? (What keywords or phrases?)
• What are the main use cases?

About Tools:

• Does it need to read files? (Read, Grep, Glob)
• Execute commands? (Bash)
• Modify files? (Edit, Write)
• Access web? (WebFetch)

About Packaging:

• npm scope or no scope?
  • With scope: @mycompany/skill-name
  • Without: skill-name
• Skill name (lowercase with hyphens only, max 64 chars)

About Target Tools:

• Which AI tools do they use?
  • Claude Code (always enabled)
  • Cursor?
  • Windsurf?
  • Other?

Step 3: Customize Configuration

Help them update these files:

package.json

{
  "name": "@user-org/skill-name",
  "description": "[Clear description]",
  "author": "[Name <email>]",
  "keywords": ["claude-code", "skill", "[relevant-keywords]"],
  "repository": {
    "url": "https://github.com/[username]/[repo].git"
  }
}

.claude-skill.json

{
  "name": "skill-name",
  "package": "@user-org/skill-name",
  "targets": {
    "claude-code": { "enabled": true },
    "cursor": { "enabled": [true/false] }
  }
}

Step 4: Write SKILL.md (MOST IMPORTANT)

Help them create a comprehensive SKILL.md:

Frontmatter (CRITICAL):

---
name: skill-name
description: [What it does] and when to use it. Use when [scenarios]. Include trigger keywords.
allowed-tools: [Tools it needs]
---

✅ Good descriptions:

• "Generates conventional commit messages from git diffs. Use when writing commits, creating commit messages, or reviewing staged changes."
• "Analyzes Python code for type errors. Use when checking Python types, debugging type issues, or validating .py files."

❌ Bad descriptions:

• "Helps with files" (too vague)
• "A useful tool" (no keywords)

Description Guidelines:

1. Start with action verb + what it does
2. Add "Use when [scenarios]"
3. Include natural keywords users would say
4. Be specific about file types, actions, domains
5. Keep under 1024 characters

Main Content Structure:

# Skill Name

[Brief introduction]

## Instructions

When [user scenario]:

1. **First Step**: [Action]
   - [Details]

2. **Second Step**: [Action]
   - [Details]

3. **Final Step**: [Result]
   - [Output format]

## Examples

### Example 1: [Scenario]

User asks: "[Question]"

What happens:
1. [Step]
2. [Step]
3. [Result]

## Best Practices

- [Practice 1]
- [Practice 2]

Step 5: Add Supporting Files (If Needed)

For complex skills, use progressive disclosure:

reference.md - Detailed docs (loaded only when needed):

• Complete API reference
• Advanced patterns
• Configuration options

examples.md - More examples:

• Real-world scenarios
• Edge cases
• Integration patterns

scripts/ - Utility scripts (zero-context execution):

• Validation logic
• Data processing

Link from SKILL.md:

For details, see [reference.md](reference.md)

Keep SKILL.md under 500 lines!

Step 6: Test Locally

Help them test:

# Test installation
npm test

# Or manually
node install-skill.js

# Verify installed
ls -la ~/.claude/skills/[skill-name]/
cat ~/.claude/skills/[skill-name]/SKILL.md

In Claude Code:

• Ask: "What skills are available?"
• Verify skill appears
• Test with trigger phrases
• Check tool access
• Verify behavior

Testing checklist:

• [ ] Appears in skills list
• [ ] Triggers on keywords
• [ ] Has tool access
• [ ] Works as intended
• [ ] Clear documentation

Step 7: Publish to npm

Guide publishing:

# One-time setup
npm login

# Publish (scoped packages need --access public)
npm publish --access public

# Verify
npm view @user-org/skill-name

Pre-publish checklist:

• [ ] All placeholders replaced
• [ ] README updated
• [ ] Tested locally
• [ ] Git committed
• [ ] Version tagged

Step 8: Share and Iterate

Encourage them to:

• Share with community
• Gather feedback
• Improve iteratively
• Contribute examples

Common Skill Patterns

Pattern 1: File Analyzer

When: Analyze specific file types

name: file-analyzer
description: Analyzes [file-type] for [purpose]. Use when checking [file-type], analyzing [aspect], or validating [file-type] files.
allowed-tools: Read, Grep, Glob

Structure:

1. Find files
2. Read and parse
3. Analyze
4. Report findings

Pattern 2: Code Generator

When: Generate code/docs

name: code-generator
description: Generates [artifact] from [input]. Use when creating [thing], generating [stuff], or scaffolding [structure].
allowed-tools: Read, Write, Bash

Structure:

1. Gather requirements
2. Read templates
3. Generate content
4. Write output
5. Verify

Pattern 3: Workflow Automation

When: Automate processes

name: workflow-helper
description: Automates [workflow]. Use when [action]ing [thing], running [process], or executing [workflow].
allowed-tools: Bash, Read, Edit

Structure:

1. Check preconditions
2. Execute steps
3. Verify completion

Troubleshooting

Skill Not Triggering

Cause: Poor description

Fix:

1. Add more trigger keywords to description
2. Make description more specific
3. Test with exact keywords
4. Or ask explicitly: "Use the [skill-name] skill"

Tool Access Issues

Cause: Missing from allowed-tools

Fix:

1. Add to allowed-tools in frontmatter
2. Or remove field to allow all tools

Installation Fails

Cause: Config errors

Fix:

1. Validate .claude-skill.json (must be valid JSON)
2. Check name consistency across files
3. Verify file permissions
4. Run node install-skill.js for details

Best Practices

1. Start Simple: Basic version first, enhance later
2. Clear Descriptions: Critical for skill discovery
3. Test Thoroughly: Various inputs and edge cases
4. Document Well: Good docs attract users
5. Progressive Disclosure: SKILL.md < 500 lines
6. Semantic Versioning: Follow semver
7. Gather Feedback: Improve from real usage

Quick Reference Checklist

Skill Creation:

• [ ] Clone template
• [ ] Update package.json
• [ ] Update .claude-skill.json
• [ ] Write SKILL.md (focus on description!)
• [ ] Add examples
• [ ] Test locally
• [ ] Commit to git
• [ ] Publish to npm
• [ ] Test installation
• [ ] Share!

SKILL.md Essentials:

• [ ] Clear, keyword-rich description
• [ ] Correct name (lowercase, hyphens, <64 chars)
• [ ] Appropriate allowed-tools
• [ ] Step-by-step instructions
• [ ] Concrete examples
• [ ] Best practices
• [ ] Links to reference docs (if needed)

Resources

• Boilerplate
• Official Docs
• Best Practices
• Multi-Tool Support

---

Remember: The description field is everything. Spend time making it clear, specific, and keyword-rich. This single field determines when Claude uses the skill!