tomevault-io Skill Creator
A meta-skill for generating new Claude Code skills with proper structure and validation.
When to Use
- Creating project-specific skills (e.g., "Odyssey design system components")
- Building work-related skills (e.g., "SD API client generation")
- Generating custom workflow automations
- Standardizing team practices into reusable skills
- Converting manual processes into automated skills
Core Workflow
1. Gather Requirements
Ask the user:
- Purpose: What problem does this skill solve?
- Triggers: What keywords/phrases should activate it?
- Context: When should it be used (file types, project types)?
- Location: Where to save (global or project-local)?
- Dependencies: Required tools, packages, or other skills?
2. Generate Skill Structure
Template Reference: See templates/skill_template.md for the complete skill template with all available fields and examples.
Create a properly formatted SKILL.md with:
---
# OFFICIAL CLAUDE CODE FIELDS (recognized by Claude Code)
name: skill-identifier # Required: kebab-case
description: | # Required: What it does AND when to activate
Clear description of what it does and when to use it.
IMPORTANT: Include activation triggers in the description itself.
Example: "Generate React components. Use when creating new UI components."
allowed-tools: [] # Optional: Restrict to specific tools
# EXTENDED METADATA (ignored by Claude Code, useful for organization)
version: 1.0.0 # Track changes (skills are files, not packages)
---
# Skill Name
Brief overview (1-2 sentences).
## When to Use
- Concrete trigger 1
- Concrete trigger 2
- Specific scenario 3
## Core Workflow
### 1. First Step
Description and instructions
### 2. Second Step
Description and instructions
## Best Practices
- Practice 1
- Practice 2
## Example Workflows
### Scenario 1: Common Use Case
Step-by-step example
### Scenario 2: Edge Case
How to handle edge cases
## Integration Points
- Works with: [other skills]
- Calls: [agents/tools]
- Required by: [dependent skills]
## Troubleshooting
### Issue 1
Symptom: [description]
Solution: [fix]
### Issue 2
Symptom: [description]
Solution: [fix]
## References
- [External documentation links]
3. Validate Against Specifications
Ensure the skill follows:
Anthropic Best Practices:
- ✅ Clear, actionable instructions
- ✅ Specific triggers (not generic)
- ✅ Real examples (not placeholders)
- ✅ Token-efficient (< 500 lines for core content)
- ✅ Progressive disclosure (link to API_REFERENCE.md if needed)
RED-GREEN-REFACTOR Ready:
- ✅ Can be tested without the skill (RED phase)
- ✅ Verifiable compliance (GREEN phase)
- ✅ Hardened against rationalizations (REFACTOR phase)
Community Patterns:
- ✅ No TODOs or placeholders in production
- ✅ No "YOUR_KEY_HERE" style configs
- ✅ Specific, not generic labels
- ✅ Context-aware activation
4. Save to Appropriate Location
Global Skills (general use across all projects):
~/.claude/skills/super-claude/plugins/[category]/skills/skill-name.md
Project-Local Skills (specific to one project):
/path/to/project/.claude/skills/skill-name.md
Note: Project-local skills are perfect for work-specific or proprietary patterns that shouldn't be shared globally.
5. Test the Skill
Provide testing guidance:
- RED: Try the workflow WITHOUT the skill, note failures
- GREEN: Enable the skill, verify it works
- REFACTOR: Identify edge cases, harden the skill
Skill Types
Standard Skill (Most Common)
General-purpose automation or guidance for specific tasks.
Component Generator
Creates code/files following specific patterns.
Workflow Orchestrator
Coordinates multiple steps or tools.
Validation/Checker
Ensures code/config meets standards.
Migration Helper
Assists in moving between technologies.
Advanced Features
Progressive Disclosure
If skill exceeds 500 lines, split into:
- SKILL.md: Core instructions (< 500 lines)
- API_REFERENCE.md: Advanced topics (loaded on-demand)
Link from SKILL.md:
For advanced usage, see [API_REFERENCE.md](./API_REFERENCE.md)
Context-Aware Activation
Make skills activate automatically:
triggers:
keywords: [specific, technical, terms]
patterns: ['regex.*patterns']
contexts: [file-types, project-types]
Dependencies
Declare requirements:
requires:
tools: [git, npm, docker]
skills: [typescript/tsc-validation]
packages: ['@types/node']
Auto-Activation System
Overview
Skills can auto-activate based on user prompts using the skill-rules.json system. This enables Claude to proactively suggest relevant skills before responding.
For complete details, see: SKILL_ACTIVATION_GUIDE.md
When to Add Activation Rules
Add skill-rules.json entries when:
- Skill is part of a plugin (not project-local)
- Skill should auto-activate from specific keywords
- Skill addresses a common workflow pattern
- Skill is high-value and frequently needed
Skip activation rules for:
- One-off project-specific skills
- Rarely-used experimental skills
- Skills that should only run on explicit user request
Creating skill-rules.json Entries
For plugin developers: Add entries to plugins/{plugin}/skills/skill-rules.json
Schema:
{
"plugin": {
"name": "plugin-name",
"version": "1.0.0",
"namespace": "namespace"
},
"skills": {
"skill-name": {
"type": "domain",
"enforcement": "suggest",
"priority": "high",
"description": "Brief description of what the skill does",
"promptTriggers": {
"keywords": ["keyword1", "keyword2"],
"intentPatterns": ["pattern1", "pattern2"]
}
}
}
}
Writing Good Keywords
✅ Good Keywords (specific, unambiguous):
"keywords": [
"create skill",
"new skill",
"skill template",
"generate skill",
"skill development"
]
❌ Bad Keywords (too generic):
"keywords": [
"create",
"new",
"help",
"build"
]
Rules for keywords:
- Minimum 2 words for specificity
- Include the domain (e.g., "skill", "hook", "component")
- Match how users naturally ask for help
- Case-insensitive literal matching
- No regex needed for keywords
Writing Good Intent Patterns
✅ Good Patterns (capture intent, not exact wording):
"intentPatterns": [
"(create|add|generate|build).*?skill",
"how to.*?(create|add|build).*?skill",
"skill.*?(template|generator|builder)",
"need.*?skill.*?(for|to)",
"(make|write).*?skill"
]
❌ Bad Patterns (too broad or too narrow):
"intentPatterns": [
".*skill.*",
"^create exactly this specific phrase$"
]
Rules for patterns:
- Use regex with case-insensitive flag (
i) - Include action verbs: create, add, generate, build, make
- Include domain terms: skill, hook, component, etc.
- Use
.*?for flexible matching between keywords - Capture natural variations of the same intent
Priority Guidelines
critical - Must run for safety/correctness:
"priority": "critical"
// Examples: security validators, syntax checkers
high - Highly recommended:
"priority": "high"
// Examples: skill-creator, component-generator
medium - Useful but optional:
"priority": "medium"
// Examples: documentation generators, formatters
low - Nice-to-have:
"priority": "low"
// Examples: experimental features, rarely-used tools
Example: skill-creator Activation Rules
{
"plugin": {
"name": "meta",
"version": "1.0.0",
"namespace": "claude"
},
"skills": {
"skill-creator": {
"type": "domain",
"enforcement": "suggest",
"priority": "high",
"description": "Generate new Claude Code skills with proper structure and validation",
"promptTriggers": {
"keywords": [
"create skill",
"new skill",
"skill development",
"generate skill",
"skill template"
],
"intentPatterns": [
"(create|add|generate|build).*?skill",
"how to.*?(create|add|build).*?skill",
"skill.*?(template|generator|builder)",
"need.*?skill.*?(for|to)",
"(make|write).*?skill"
]
}
}
}
}
Migration Tool
Use /generate-skill-rules to auto-generate entries from existing SKILL.md YAML frontmatter:
# Preview generated rules
/generate-skill-rules --plugin plugins/tanstack-tools --namespace tanstack
# Write to skill-rules.json
/generate-skill-rules --plugin plugins/api-tools --namespace api --write
Testing Activation Rules
Test in isolated project:
# 1. Create test project
mkdir test-activation && cd test-activation
# 2. Copy hook and rules
mkdir -p .claude/hooks .claude/skills/your-plugin
cp {hook-path}/skill-activation-prompt.ts .claude/hooks/
cp {plugin-path}/skill-rules.json .claude/skills/your-plugin/
# 3. Test with prompts
echo '{"prompt":"create a new skill","cwd":"'$(pwd)'"}' | \
bun run .claude/hooks/skill-activation-prompt.ts
Expected output:
============================================================
SKILL ACTIVATION CHECK
============================================================
[RECOMMENDED] SKILLS:
-> skill-creator
ACTION: Use Skill tool BEFORE responding
============================================================
Workflow: Adding Auto-Activation to New Skills
When creating a skill that should auto-activate:
Create the SKILL.md (as normal)
Identify triggers by asking:
- What keywords would users type to need this skill?
- What questions or requests indicate this intent?
- How do users naturally express this need?
Add to skill-rules.json:
{ "skills": { "new-skill": { "type": "domain", "enforcement": "suggest", "priority": "high", "description": "What the skill does", "promptTriggers": { "keywords": ["keyword1", "keyword2"], "intentPatterns": ["pattern1", "pattern2"] } } } }Test the triggers:
- Try prompts that SHOULD activate it
- Try prompts that should NOT activate it
- Refine keywords/patterns based on results
Document in SKILL.md:
## Auto-Activation This skill auto-activates when you mention: - Creating/generating {domain objects} - Specific workflow requests - Related keywords Triggered by: create skill, new skill, generate skill
Project-Level Overrides
Users can customize activation in their projects via .claude/skills/skill-rules.json:
{
"version": "1.0",
"overrides": {
"claude/skill-creator": {
"priority": "critical"
}
},
"disabled": ["claude/skill-validator"],
"global": {
"maxSkillsPerPrompt": 3,
"priorityThreshold": "medium"
}
}
Command for users: /workflow:configure
Example: Creating a Project-Specific Skill
User Request: "Create a skill for generating Odyssey design system components"
Generated Skill:
Location: /path/to/odyssey-project/.claude/skills/odyssey-components.md
---
name: odyssey-components
version: 1.0.0
description: |
Generate components following Odyssey design system guidelines.
Ensures consistency with design tokens, patterns, and accessibility standards.
category: design-system
tags: [odyssey, components, design-system, react]
model: sonnet
requires:
tools: [npm]
packages: ["@odyssey/design-tokens", "@odyssey/components"]
triggers:
keywords: [odyssey, odyssey component, design system]
patterns: ["create.*odyssey", "generate.*odyssey"]
---
# Odyssey Components
Generate React components that follow Odyssey design system standards.
## When to Use
- Creating new Odyssey components
- Ensuring design system compliance
- Maintaining consistency across products
## Component Structure
All components follow this pattern:
\`\`\`
components/
└── ComponentName/
├── ComponentName.tsx
├── ComponentName.stories.tsx
├── ComponentName.test.tsx
└── index.ts
\`\`\`
## Design Token Usage
Always use design tokens from `@odyssey/design-tokens`:
\`\`\`typescript
import { tokens } from '@odyssey/design-tokens'
const styles = {
color: tokens.color.primary.base,
spacing: tokens.spacing.md,
borderRadius: tokens.borderRadius.md
}
\`\`\`
## Accessibility Requirements
All components must:
- Meet WCAG AAA standards
- Include proper ARIA labels
- Support keyboard navigation
- Provide focus indicators
## Example: Button Component
[Detailed example following Odyssey patterns]
Common Skill Patterns
API Client Generator
name: project-api-client
purpose: Generate type-safe API clients from OpenAPI schemas
includes: OpenAPI schema parsing, type generation, RPC helpers
location: project-local (for proprietary APIs)
Component Library Helper
name: design-system-components
purpose: Generate components following project design system
includes: Component patterns, theme support, testing
location: project-local (for proprietary design systems)
Database Schema Generator
name: drizzle-schema-from-db
purpose: Generate Drizzle schemas from existing Postgres database
includes: Type inference, relationship mapping, migration helpers
location: global (reusable across projects)
Deployment Automation
name: coolify-deployment
purpose: Automate deployment to Coolify platform
includes: Docker config, environment setup, rollback procedures
location: global (reusable deployment pattern)
Best Practices
- Be Specific: Don't create "helper" or "utility" skills - be explicit about what they do
- Include Examples: Real, working examples - not placeholders
- Test First: RED-GREEN-REFACTOR methodology ensures quality
- Token Efficiency: Keep core content under 500 lines
- Clear Triggers: Specific keywords that clearly indicate when to activate
- Validate: Always check against Claude Code and Anthropic specs
Anti-Patterns to Avoid
- ❌ Generic names ("helper", "utils", "tool")
- ❌ TODOs or placeholders in production
- ❌ Narrative examples tied to specific sessions
- ❌ Code embedded in flowcharts
- ❌ Missing activation triggers
- ❌ Over 500 lines without progressive disclosure
- ❌ Untested skills
Integration with Other Tools
shadcn CLI Integration
# Generate skill that wraps shadcn commands
pnpm dlx shadcn@latest add [component]
pnpm dlx shadcn@latest add @coss/[component]
Registry Support
Skills can integrate with component registries:
- shadcn/ui registry
- coss.com/ui registry
- Custom private registries
Troubleshooting
Skill Not Activating
Symptom: Skill exists but doesn't trigger Solution:
- Check triggers section in YAML frontmatter
- Ensure keywords are specific enough
- Verify file is in correct location
- Check Claude Code loaded the skill (restart if needed)
Skill Too Generic
Symptom: Skill triggers too often or in wrong contexts Solution:
- Make keywords more specific
- Add context restrictions
- Use regex patterns to narrow activation
Skill Too Large
Symptom: Skill exceeds 500 lines Solution:
- Implement progressive disclosure
- Move advanced content to API_REFERENCE.md
- Keep core workflow in SKILL.md
References
- Claude Code Skills Documentation
- Anthropic Best Practices
- obra/superpowers - Community patterns
- super-claude CREATING_SKILLS.md - RED-GREEN-REFACTOR guide
Converted and distributed by TomeVault — claim your Tome and manage your conversions.