skill-builder

Name: skill-builder
Author: spencermarx

301stars24forks

How to install skill-builder?

spencermarx/open-code-review/skill-builder

$npx -y skills add spencermarx/open-code-review --skill skill-builder

Installs into the current project.

Summary

Create new Claude Code Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organization. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Claude Skills specification.

Files · 1

View on GitHub

SKILL.md

1	# Skill Builder
2
3	## What This Skill Does
4
5	Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file/folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API).
6
7	## Prerequisites
8
9	- Claude Code 2.0+ or Claude.ai with Skills support
10	- Basic understanding of Markdown and YAML
11	- Text editor or IDE
12
13	## Quick Start
14
15	### Creating Your First Skill
16
17	```bash
18	# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
19	mkdir -p ~/.claude/skills/my-first-skill
20
21	# 2. Create SKILL.md with proper format
22	cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
23	---
24	name: "My First Skill"
25	description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
26	---
27
28	# My First Skill
29
30	## What This Skill Does
31	[Your instructions here]
32
33	## Quick Start
34	[Basic usage]
35	EOF
36
37	# 3. Verify skill is detected
38	# Restart Claude Code or refresh Claude.ai
39	```
40
41	---
42
43	## Complete Specification
44
45	### 📋 YAML Frontmatter (REQUIRED)
46
47	Every SKILL.md must start with YAML frontmatter containing exactly two required fields:
48
49	```yaml
50	---
51	name: "Skill Name" # REQUIRED: Max 64 chars
52	description: "What this skill does # REQUIRED: Max 1024 chars
53	and when Claude should use it." # Include BOTH what & when
54	---
55	```
56
57	#### Field Requirements
58
59	`name` (REQUIRED):
60	- Type: String
61	- Max Length: 64 characters
62	- Format: Human-friendly display name
63	- Usage: Shown in skill lists, UI, and loaded into Claude's system prompt
64	- Best Practice: Use Title Case, be concise and descriptive
65	- Examples:
66	- ✅ "API Documentation Generator"
67	- ✅ "React Component Builder"
68	- ✅ "Database Schema Designer"
69	- ❌ "skill-1" (not descriptive)
70	- ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)
71
72	`description` (REQUIRED):
73	- Type: String
74	- Max Length: 1024 characters
75	- Format: Plain text or minimal markdown
76	- Content: MUST include:
77	1. What the skill does (functionality)
78	2. When Claude should invoke it (trigger conditions)
79	- Usage: Loaded into Claude's system prompt for autonomous matching
80	- Best Practice: Front-load key trigger words, be specific about use cases
81	- Examples:
82	- ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
83	- ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
84	- ❌ "A comprehensive guide to API documentation" (no "when" clause)
85	- ❌ "Documentation tool" (too vague)
86
87	#### YAML Formatting Rules
88
89	```yaml
90	---
91	# ✅ CORRECT: Simple string
92	name: "API Builder"
93	description: "Creates REST APIs with Express and TypeScript."
94
95	# ✅ CORRECT: Multi-line description
96	name: "Full-Stack Generator"
97	description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."
98
99	# ✅ CORRECT: Special characters quoted
100	name: "JSON:API Builder"
101	description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."
102
103	# ❌ WRONG: Missing quotes with special chars
104	name: API:Builder # YAML parse error!
105
106	# ❌ WRONG: Extra fields (ignored but discouraged)
107	name: "My Skill"
108	description: "My description"
109	version: "1.0.0" # NOT part of spec
110	author: "Me" # NOT part of spec
111	tags: ["dev", "api"] # NOT part of spec
112	---
113	```
114
115	Critical: Only `name` and `description` are used by Claude. Additional fields are ignored.
116
117	---
118
119	### 📂 Directory Structure
120
121	#### Minimal Skill (Required)
122	```
123	~/.claude/skills/ # Personal skills location
124	└── my-skill/ # Skill directory (MUST be at top level!)
125	└── SKILL.md # REQUIRED: Main skill file
126	```
127
128	IMPORTANT: Skills MUST be directly under `~/.claude/skills/[skill-name]/`.
129	Claude Code does NOT support nested subdirectories or namespaces!
130
131	#### Full-Featured Skill (Recommended)
132	```
133	~/.claude/skills/
134	└── my-skill/ # Top-level skill directory
135	├── SKILL.md # REQUIRED: Main skill file
136	├── README.md # Optional: Human-readable docs
137	├── scripts/ # Optional: Executable scripts
138	│ ├── setup.sh
139	│ ├── validate.js
140	│ └── deploy.py
141	├── resources/ # Optional: Supporting files
142	│ ├── templates/
143	│ │ ├── api-templ

People who liked this also viewed

6 picks

Type

skill-builder

301stars24forks

View on GitHub

How to install skill-builder?

spencermarx/open-code-review/skill-builder

$npx -y skills add spencermarx/open-code-review --skill skill-builder

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill Builder
2
3	## What This Skill Does
4
5	Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file/folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API).
6
7	## Prerequisites
8
9	- Claude Code 2.0+ or Claude.ai with Skills support
10	- Basic understanding of Markdown and YAML
11	- Text editor or IDE
12
13	## Quick Start
14
15	### Creating Your First Skill
16
17	```bash
18	# 1. Create skill directory (MUST be at top level, NOT in subdirectories!)
19	mkdir -p ~/.claude/skills/my-first-skill
20
21	# 2. Create SKILL.md with proper format
22	cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF'
23	---
24	name: "My First Skill"
25	description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters."
26	---
27
28	# My First Skill
29
30	## What This Skill Does
31	[Your instructions here]
32
33	## Quick Start
34	[Basic usage]
35	EOF
36
37	# 3. Verify skill is detected
38	# Restart Claude Code or refresh Claude.ai
39	```
40
41	---
42
43	## Complete Specification
44
45	### 📋 YAML Frontmatter (REQUIRED)
46
47	Every SKILL.md must start with YAML frontmatter containing exactly two required fields:
48
49	```yaml
50	---
51	name: "Skill Name" # REQUIRED: Max 64 chars
52	description: "What this skill does # REQUIRED: Max 1024 chars
53	and when Claude should use it." # Include BOTH what & when
54	---
55	```
56
57	#### Field Requirements
58
59	`name` (REQUIRED):
60	- Type: String
61	- Max Length: 64 characters
62	- Format: Human-friendly display name
63	- Usage: Shown in skill lists, UI, and loaded into Claude's system prompt
64	- Best Practice: Use Title Case, be concise and descriptive
65	- Examples:
66	- ✅ "API Documentation Generator"
67	- ✅ "React Component Builder"
68	- ✅ "Database Schema Designer"
69	- ❌ "skill-1" (not descriptive)
70	- ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)
71
72	`description` (REQUIRED):
73	- Type: String
74	- Max Length: 1024 characters
75	- Format: Plain text or minimal markdown
76	- Content: MUST include:
77	1. What the skill does (functionality)
78	2. When Claude should invoke it (trigger conditions)
79	- Usage: Loaded into Claude's system prompt for autonomous matching
80	- Best Practice: Front-load key trigger words, be specific about use cases
81	- Examples:
82	- ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
83	- ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
84	- ❌ "A comprehensive guide to API documentation" (no "when" clause)
85	- ❌ "Documentation tool" (too vague)
86
87	#### YAML Formatting Rules
88
89	```yaml
90	---
91	# ✅ CORRECT: Simple string
92	name: "API Builder"
93	description: "Creates REST APIs with Express and TypeScript."
94
95	# ✅ CORRECT: Multi-line description
96	name: "Full-Stack Generator"
97	description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications."
98
99	# ✅ CORRECT: Special characters quoted
100	name: "JSON:API Builder"
101	description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships."
102
103	# ❌ WRONG: Missing quotes with special chars
104	name: API:Builder # YAML parse error!
105
106	# ❌ WRONG: Extra fields (ignored but discouraged)
107	name: "My Skill"
108	description: "My description"
109	version: "1.0.0" # NOT part of spec
110	author: "Me" # NOT part of spec
111	tags: ["dev", "api"] # NOT part of spec
112	---
113	```
114
115	Critical: Only `name` and `description` are used by Claude. Additional fields are ignored.
116
117	---
118
119	### 📂 Directory Structure
120
121	#### Minimal Skill (Required)
122	```
123	~/.claude/skills/ # Personal skills location
124	└── my-skill/ # Skill directory (MUST be at top level!)
125	└── SKILL.md # REQUIRED: Main skill file
126	```
127
128	IMPORTANT: Skills MUST be directly under `~/.claude/skills/[skill-name]/`.
129	Claude Code does NOT support nested subdirectories or namespaces!
130
131	#### Full-Featured Skill (Recommended)
132	```
133	~/.claude/skills/
134	└── my-skill/ # Top-level skill directory
135	├── SKILL.md # REQUIRED: Main skill file
136	├── README.md # Optional: Human-readable docs
137	├── scripts/ # Optional: Executable scripts
138	│ ├── setup.sh
139	│ ├── validate.js
140	│ └── deploy.py
141	├── resources/ # Optional: Supporting files
142	│ ├── templates/
143	│ │ ├── api-templ

People who liked this also viewed

6 picks

Type