skill-factory
Create new skills with proper structure and YAML frontmatter. Use when building new slash command skills, ensuring consistent formatting, directory structure, and validation. Guides through the complete skill creation workflow.
When & Why to Use This Skill
The Skill Factory is a specialized developer tool designed to automate and standardize the creation of new Claude agent capabilities. It streamlines the development lifecycle by generating consistent directory structures, enforcing YAML frontmatter standards, and providing a validated template for SKILL.md files. This ensures all custom slash commands are discoverable, well-documented, and follow best practices for agentic workflows.
Use Cases
- Rapid Scaffolding: Quickly generate the boilerplate structure for new slash commands, including the .claude/skills/ directory and required metadata.
- Standardization & Compliance: Enforce project-wide standards for skill naming (kebab-case), documentation structure, and escalation rules to maintain a clean codebase.
- Automated Validation: Audit existing skill files to ensure YAML frontmatter is valid and all required sections like 'When to Use' and 'Required Actions' are present.
- Complex Workflow Organization: Automatically set up optional 'Reference/' and 'Workflows/' subdirectories for skills that require extensive external context or multi-step execution logic.
| name | skill-factory |
|---|---|
| description | Create new skills with proper structure and YAML frontmatter. Use when building new slash command skills, ensuring consistent formatting, directory structure, and validation. Guides through the complete skill creation workflow. |
| model_tier | sonnet |
| can_parallel_with | [agent-factory] |
| must_serialize_with | [] |
| preferred_batch_size | 1 |
| max_file_context | 40 |
| compression_level | 1 |
| requires_git_context | true |
| requires_db_context | false |
| - pattern | "duplicate|conflict" |
| reason | "System-level changes require review" |
| - keyword | ["critical system", "agent permissions"] |
Skill Factory
Purpose: Guide users through creating new Claude Code skills with proper structure Created: 2025-12-27 Trigger:
/skill-factorycommand
When to Use
- Creating a new slash command skill
- Need to ensure proper YAML frontmatter format
- Want consistent skill structure across the project
- Building skills for agents or workflows
- Validating existing skill files
Required Actions
When this skill is invoked, Claude MUST:
Gather skill requirements from the user:
- Skill name (kebab-case, e.g.,
my-new-skill) - One-line description (for slash command discovery)
- Purpose and use cases
- Whether it needs Reference/ or Workflows/ subdirectories
- Skill name (kebab-case, e.g.,
Validate the skill name:
- Must be kebab-case
- Must not conflict with existing skills
- Must be descriptive and discoverable
Create the directory structure:
.claude/skills/<skill-name>/ ├── SKILL.md # Required: Main skill file ├── Reference/ # Optional: Reference documentation └── Workflows/ # Optional: Workflow definitionsGenerate SKILL.md using the template below
Validate the created skill:
- YAML frontmatter is valid
- Required sections are present
- Examples are included
Skill Template
Use this template for all new skills:
---
name: <skill-name>
description: <one-line description for slash command discovery>
---
# <Skill Title>
> **Purpose:** <what this skill does>
> **Created:** <date>
> **Trigger:** `/<skill-name>` command
---
## When to Use
<bullet list of scenarios when this skill should be used>
---
## Required Actions
When this skill is invoked, Claude MUST:
1. <action 1>
2. <action 2>
3. <action 3>
---
## Examples
<usage examples showing how the skill works>
---
## Escalation Rules
**Escalate to human when:**
<list of situations requiring human intervention>
**Can handle automatically:**
<list of situations the skill can handle independently>
---
## Related
- <related skills>
- <related documentation>
Validation Checklist
Before completing skill creation, verify:
YAML Frontmatter Valid
name:matches directory name (kebab-case)description:is one line, under 200 characters- No trailing spaces or invalid YAML syntax
Required Sections Present
- Title with Purpose/Created/Trigger metadata
- "When to Use" section with bullet points
- "Required Actions" section with numbered steps
- "Examples" section with concrete usage
Quality Standards
- Description is discoverable (keywords users would search)
- Actions are specific and actionable
- Examples demonstrate real use cases
- Escalation rules define boundaries
No Conflicts
- Skill name doesn't duplicate existing skill
- Functionality doesn't overlap significantly with existing skills
Directory Structure Correct
.claude/skills/<skill-name>/SKILL.mdexists- Optional subdirectories created if needed
Examples
Example 1: Create a Simple Skill
User: Create a skill for generating changelogs
Claude:
- Gathers requirements: name=
changelog-generator, purpose=generate changelogs from git history - Creates directory:
.claude/skills/changelog-generator/ - Generates SKILL.md with proper frontmatter
- Validates all checklist items pass
Example 2: Create a Skill with Reference Docs
User: Create a skill for ACGME compliance with reference documentation
Claude:
- Gathers requirements including reference materials needed
- Creates structure:
.claude/skills/acgme-compliance/ ├── SKILL.md └── Reference/ ├── hour-limits.md └── supervision-ratios.md - Populates reference files as needed
Example 3: Check Existing Skill
User: Validate the test-writer skill
Claude:
- Reads
.claude/skills/test-writer/SKILL.md - Validates YAML frontmatter
- Checks all required sections present
- Reports any issues found
Escalation Rules
Escalate to human when:
- Skill affects security (auth, credentials, secrets)
- Skill duplicates existing functionality significantly
- Skill requires new agent permissions
- Unclear whether skill or agent is appropriate
- Skill would modify critical system files
Can handle automatically:
- Creating standard skill structure
- Generating SKILL.md from template
- Validating existing skills
- Creating Reference/ and Workflows/ subdirectories
- Checking for naming conflicts
Integration with TOOLSMITH Agent
This skill implements part of the TOOLSMITH agent's "Create New Skill" workflow:
- TOOLSMITH receives skill creation request
- Invokes
/skill-factoryto generate structure - Validates output meets quality standards
- Reports completion to ORCHESTRATOR
For agent creation, use the /agent-factory skill instead.
Related
.claude/Agents/TOOLSMITH.md- Agent specification for tool creation.claude/skills/- Directory containing all project skillsdocs/development/AGENT_SKILLS.md- Agent skills referenceCLAUDE.md- Project guidelines and standards