鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

skill-builder

提供从零构建 Claude Code 技能的完整方法论,涵盖标准化 YAML 元数据定义、渐进式内容分层设计及规范化的目录组织,支持快速生成可被 Claude 自动识别与调用的生产级技能。

效率工具文档处理数据与分析
访问 GitHub
文档Skills.MD
name
Skill Builder
description
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.

Skill Builder

What This Skill Does

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).

Prerequisites

  • Claude Code 2.0+ or Claude.ai with Skills support
  • Basic understanding of Markdown and YAML
  • Text editor or IDE

Quick Start

Creating Your First Skill

▼
bash
复制代码
# 1. Create skill directory (MUST be at top level, NOT in subdirectories!) mkdir -p ~/.claude/skills/my-first-skill # 2. Create SKILL.md with proper format cat > ~/.claude/skills/my-first-skill/SKILL.md << 'EOF' --- name: "My First Skill" description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters." --- # My First Skill ## What This Skill Does [Your instructions here] ## Quick Start [Basic usage] EOF # 3. Verify skill is detected # Restart Claude Code or refresh Claude.ai

Complete Specification

📋 YAML Frontmatter (REQUIRED)

Every SKILL.md must start with YAML frontmatter containing exactly two required fields:

▼
yaml
复制代码
--- name: "Skill Name" # REQUIRED: Max 64 chars description: "What this skill does # REQUIRED: Max 1024 chars and when Claude should use it." # Include BOTH what & when ---

Field Requirements

name (REQUIRED):

  • Type: String
  • Max Length: 64 characters
  • Format: Human-friendly display name
  • Usage: Shown in skill lists, UI, and loaded into Claude's system prompt
  • Best Practice: Use Title Case, be concise and descriptive
  • Examples:
    • ✅ "API Documentation Generator"
    • ✅ "React Component Builder"
    • ✅ "Database Schema Designer"
    • ❌ "skill-1" (not descriptive)
    • ❌ "This is a very long skill name that exceeds sixty-four characters" (too long)

description (REQUIRED):

  • Type: String
  • Max Length: 1024 characters
  • Format: Plain text or minimal markdown
  • Content: MUST include:
    1. What the skill does (functionality)
    2. When Claude should invoke it (trigger conditions)
  • Usage: Loaded into Claude's system prompt for autonomous matching
  • Best Practice: Front-load key trigger words, be specific about use cases
  • Examples:
    • ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
    • ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components."
    • ❌ "A comprehensive guide to API documentation" (no "when" clause)
    • ❌ "Documentation tool" (too vague)

YAML Formatting Rules

▼
yaml
复制代码
--- # ✅ CORRECT: Simple string name: "API Builder" description: "Creates REST APIs with Express and TypeScript." # ✅ CORRECT: Multi-line description name: "Full-Stack Generator" description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications." # ✅ CORRECT: Special characters quoted name: "JSON:API Builder" description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships." # ❌ WRONG: Missing quotes with special chars name: API:Builder # YAML parse error! # ❌ WRONG: Extra fields (ignored but discouraged) name: "My Skill" description: "My description" version: "1.0.0" # NOT part of spec author: "Me" # NOT part of spec tags: ["dev", "api"] # NOT part of spec ---

Critical: Only name and description are used by Claude. Additional fields are ignored.


📂 Directory Structure

Minimal Skill (Required)

▼
text
复制代码
~/.claude/skills/ # Personal skills location └── my-skill/ # Skill directory (MUST be at top level!) └── SKILL.md # REQUIRED: Main skill file

IMPORTANT: Skills MUST be directly under ~/.claude/skills/[skill-name]/. Claude Code does NOT support nested subdirectories or namespaces!

Full-Featured Skill (Recommended)

▼
text
复制代码
~/.claude/skills/ └── my-skill/ # Top-level skill directory ├── SKILL.md # REQUIRED: Main skill file ├── README.md # Optional: Human-readable docs ├── scripts/ # Optional: Executable scripts │ ├── setup.sh │ ├── validate.js │ └── deploy.py ├── resources/ # Optional: Supporting files │ ├── templates/ │ │ ├── api-template.js │ │ └── component.tsx │ ├── examples/ │ │ └── sample-output.json │ └── schemas/ │ └── config-schema.json └── docs/ # Optional: Additional documentation ├── ADVANCED.md ├── TROUBLESHOOTING.md └── API_REFERENCE.md

Skills Locations

Personal Skills (available across all projects):

▼
text
复制代码
~/.claude/skills/ └── [your-skills]/
  • Path: ~/.claude/skills/ or $HOME/.claude/skills/
  • Scope: Available in all projects for this user
  • Version Control: NOT committed to git (outside repo)
  • Use Case: Personal productivity tools, custom workflows

Project Skills (team-shared, version controlled):

▼
text
复制代码
<project-root>/.claude/skills/ └── [team-skills]/
  • Path: .claude/skills/ in project root
  • Scope: Available only in this project
  • Version Control: SHOULD be committed to git
  • Use Case: Team workflows, project-specific tools, shared knowledge

🎯 Progressive Disclosure Architecture

Claude Code uses a 3-level progressive disclosure system to scale to 100+ skills without context penalty:

Level 1: Metadata (Name + Description)

Loaded: At Claude Code startup, always Size: ~200 chars per skill Purpose: Enable autonomous skill matching Context: Loaded into system prompt for ALL skills

▼
yaml
复制代码
--- name: "API Builder" # 11 chars description: "Creates REST APIs..." # ~50 chars --- # Total: ~61 chars per skill # 100 skills = ~6KB context (minimal!)

Level 2: SKILL.md Body

Loaded: When skill is triggered/matched Size: ~1-10KB typically Purpose: Main instructions and procedures Context: Only loaded for ACTIVE skills

▼
markdown
复制代码
# API Builder ## What This Skill Does [Main instructions - loaded only when skill is active] ## Quick Start [Basic procedures] ## Step-by-Step Guide [Detailed instructions]

Level 3+: Referenced Files

Loaded: On-demand as Claude navigates Size: Variable (KB to MB) Purpose: Deep reference, examples, schemas Context: Loaded only when Claude accesses specific files

▼
markdown
复制代码
# In SKILL.md See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [API Reference](docs/API_REFERENCE.md) for complete documentation. Use template: `resources/templates/api-template.js` # Claude will load these files ONLY if needed

Benefit: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context.


📝 SKILL.md Content Structure

Recommended 4-Level Structure

▼
markdown
复制代码
--- name: "Your Skill Name" description: "What it does and when to use it" --- # Your Skill Name ## Level 1: Overview (Always Read First) Brief 2-3 sentence description of the skill. ## Prerequisites - Requirement 1 - Requirement 2 ## What This Skill Does 1. Primary function 2. Secondary function 3. Key benefit --- ## Level 2: Quick Start (For Fast Onboarding) ### Basic Usage ```bash # Simplest use case command --option value

Common Scenarios

  1. Scenario 1: How to...
  2. Scenario 2: How to...

Level 3: Detailed Instructions (For Deep Work)

Step-by-Step Guide

Step 1: Initial Setup

▼
bash
复制代码
# Commands

Expected output:

▼
text
复制代码
Success message

Step 2: Configuration

  • Configuration option 1
  • Configuration option 2

Step 3: Execution

  • Run the main command
  • Verify results

Advanced Options

Option 1: Custom Configuration

▼
bash
复制代码
# Advanced usage

Option 2: Integration

▼
bash
复制代码
# Integration steps

Level 4: Reference (Rarely Needed)

Troubleshooting

Issue: Common Problem

Symptoms: What you see Cause: Why it happens Solution: How to fix

▼
bash
复制代码
# Fix command

Issue: Another Problem

Solution: Steps to resolve

Complete API Reference

See API_REFERENCE.md

Examples

See examples/

Related Skills

  • Related Skill 1
  • Related Skill 2

Resources

  • External Link 1
  • Documentation
▼
text
复制代码
--- ### 🎨 Content Best Practices #### Writing Effective Descriptions **Front-Load Keywords**: ```yaml # ✅ GOOD: Keywords first description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients." # ❌ BAD: Keywords buried description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces."

Include Trigger Conditions:

▼
yaml
复制代码
# ✅ GOOD: Clear "when" clause description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size." # ❌ BAD: No trigger conditions description: "Helps with React performance debugging."

Be Specific:

▼
yaml
复制代码
# ✅ GOOD: Specific technologies description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints." # ❌ BAD: Too generic description: "Build API endpoints with proper validation and testing."

Progressive Disclosure Writing

Keep Level 1 Brief (Overview):

▼
markdown
复制代码
## What This Skill Does Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.

Level 2 for Common Paths (Quick Start):

▼
markdown
复制代码
## Quick Start ```bash # Most common use case (80% of users) generate-component MyComponent
▼
text
复制代码
**Level 3 for Details** (Step-by-Step): ```markdown ## Step-by-Step Guide ### Creating a Basic Component 1. Run generator 2. Choose template 3. Customize options [Detailed explanations]

Level 4 for Edge Cases (Reference):

▼
markdown
复制代码
## Advanced Configuration For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md).

🛠️ Adding Scripts and Resources

Scripts Directory

Purpose: Executable scripts that Claude can run Location: scripts/ in skill directory Usage: Referenced from SKILL.md

Example:

▼
bash
复制代码
# In skill directory scripts/ ├── setup.sh # Initialization script ├── validate.js # Validation logic ├── generate.py # Code generation └── deploy.sh # Deployment script

Reference from SKILL.md:

▼
markdown
复制代码
## Setup Run the setup script: ```bash ./scripts/setup.sh

Validation

Validate your configuration:

▼
bash
复制代码
node scripts/validate.js config.json
▼
text
复制代码
#### Resources Directory **Purpose**: Templates, examples, schemas, static files **Location**: `resources/` in skill directory **Usage**: Referenced or copied by scripts Example: ```bash resources/ ├── templates/ │ ├── component.tsx.template │ ├── test.spec.ts.template │ └── story.stories.tsx.template ├── examples/ │ ├── basic-example/ │ ├── advanced-example/ │ └── integration-example/ └── schemas/ ├── config.schema.json └── output.schema.json

Reference from SKILL.md:

▼
markdown
复制代码
## Templates Use the component template: ```bash cp resources/templates/component.tsx.template src/components/MyComponent.tsx

Examples

See working examples in resources/examples/:

  • basic-example/ - Simple component
  • advanced-example/ - With hooks and context
▼
text
复制代码
--- ### 🔗 File References and Navigation Claude can navigate to referenced files automatically. Use these patterns: #### Markdown Links ```markdown See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors.

Relative File Paths

▼
markdown
复制代码
Use the template located at `resources/templates/api-template.js` See examples in `resources/examples/basic-usage/`

Inline File Content

▼
markdown
复制代码
## Example Configuration See `resources/examples/config.json`: ```json { "option": "value" }
▼
text
复制代码
**Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed. --- ### ✅ Validation Checklist Before publishing a skill, verify: **YAML Frontmatter**: - [ ] Starts with `---` - [ ] Contains `name` field (max 64 chars) - [ ] Contains `description` field (max 1024 chars) - [ ] Description includes "what" and "when" - [ ] Ends with `---` - [ ] No YAML syntax errors **File Structure**: - [ ] SKILL.md exists in skill directory - [ ] Directory is DIRECTLY in `~/.claude/skills/[skill-name]/` or `.claude/skills/[skill-name]/` - [ ] Uses clear, descriptive directory name - [ ] **NO nested subdirectories** (Claude Code requires top-level structure) **Content Quality**: - [ ] Level 1 (Overview) is brief and clear - [ ] Level 2 (Quick Start) shows common use case - [ ] Level 3 (Details) provides step-by-step guide - [ ] Level 4 (Reference) links to advanced content - [ ] Examples are concrete and runnable - [ ] Troubleshooting section addresses common issues **Progressive Disclosure**: - [ ] Core instructions in SKILL.md (~2-5KB) - [ ] Advanced content in separate docs/ - [ ] Large resources in resources/ directory - [ ] Clear navigation between levels **Testing**: - [ ] Skill appears in Claude's skill list - [ ] Description triggers on relevant queries - [ ] Instructions are clear and actionable - [ ] Scripts execute successfully (if included) - [ ] Examples work as documented --- ## Skill Builder Templates ### Template 1: Basic Skill (Minimal) ```markdown --- name: "My Basic Skill" description: "One sentence what. One sentence when to use." --- # My Basic Skill ## What This Skill Does [2-3 sentences describing functionality] ## Quick Start ```bash # Single command to get started

Step-by-Step Guide

Step 1: Setup

[Instructions]

Step 2: Usage

[Instructions]

Step 3: Verify

[Instructions]

Troubleshooting

  • Issue: Problem description
    • Solution: Fix description
▼
text
复制代码
### Template 2: Intermediate Skill (With Scripts) ```markdown --- name: "My Intermediate Skill" description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building." --- # My Intermediate Skill ## Prerequisites - Requirement 1 - Requirement 2 ## What This Skill Does 1. Primary function 2. Secondary function 3. Integration capability ## Quick Start ```bash ./scripts/setup.sh ./scripts/generate.sh my-project

Configuration

Edit config.json:

▼
json
复制代码
{ "option1": "value1", "option2": "value2" }

Step-by-Step Guide

Basic Usage

[Steps for 80% use case]

Advanced Usage

[Steps for complex scenarios]

Available Scripts

  • scripts/setup.sh - Initial setup
  • scripts/generate.sh - Code generation
  • scripts/validate.sh - Validation

Resources

  • Templates: resources/templates/
  • Examples: resources/examples/

Troubleshooting

[Common issues and solutions]

▼
text
复制代码
### Template 3: Advanced Skill (Full-Featured) ```markdown --- name: "My Advanced Skill" description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]." --- # My Advanced Skill ## Overview [Brief 2-3 sentence description] ## Prerequisites - Technology 1 (version X+) - Technology 2 (version Y+) - API keys or credentials ## What This Skill Does 1. **Core Feature**: Description 2. **Integration**: Description 3. **Automation**: Description --- ## Quick Start (60 seconds) ### Installation ```bash ./scripts/install.sh

First Use

▼
bash
复制代码
./scripts/quickstart.sh

Expected output:

▼
text
复制代码
✓ Setup complete ✓ Configuration validated → Ready to use

Configuration

Basic Configuration

Edit config.json:

▼
json
复制代码
{ "mode": "production", "features": ["feature1", "feature2"] }

Advanced Configuration

See Configuration Guide


Step-by-Step Guide

1. Initial Setup

[Detailed steps]

2. Core Workflow

[Main procedures]

3. Integration

[Integration steps]


Advanced Features

Feature 1: Custom Templates

▼
bash
复制代码
./scripts/generate.sh --template custom

Feature 2: Batch Processing

▼
bash
复制代码
./scripts/batch.sh --input data.json

Feature 3: CI/CD Integration

See CI/CD Guide


Scripts Reference

ScriptPurposeUsage
install.shInstall dependencies./scripts/install.sh
generate.shGenerate code./scripts/generate.sh [name]
validate.shValidate output./scripts/validate.sh
deploy.shDeploy to environment./scripts/deploy.sh [env]

Resources

Templates

  • resources/templates/basic.template - Basic template
  • resources/templates/advanced.template - Advanced template

Examples

  • resources/examples/basic/ - Simple example
  • resources/examples/advanced/ - Complex example
  • resources/examples/integration/ - Integration example

Schemas

  • resources/schemas/config.schema.json - Configuration schema
  • resources/schemas/output.schema.json - Output validation

Troubleshooting

Issue: Installation Failed

Symptoms: Error during install.sh Cause: Missing dependencies Solution:

▼
bash
复制代码
# Install prerequisites npm install -g required-package ./scripts/install.sh --force

Issue: Validation Errors

Symptoms: Validation script fails Solution: See Troubleshooting Guide


API Reference

Complete API documentation: API_REFERENCE.md

Related Skills

  • Related Skill 1
  • Related Skill 2

Resources

  • Official Documentation
  • GitHub Repository
  • Community Forum

Created: 2025-10-19 Category: Advanced Difficulty: Intermediate Estimated Time: 15-30 minutes

▼
text
复制代码
--- ## Examples from the Wild ### Example 1: Simple Documentation Skill ```markdown --- name: "README Generator" description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs." --- # README Generator ## What This Skill Does Creates well-structured README.md files with badges, installation, usage, and contribution sections. ## Quick Start ```bash # Answer a few questions ./scripts/generate-readme.sh # README.md created with: # - Project title and description # - Installation instructions # - Usage examples # - Contribution guidelines

Customization

Edit sections in resources/templates/sections/ before generating.

▼
text
复制代码
### Example 2: Code Generation Skill ```markdown --- name: "React Component Generator" description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns." --- # React Component Generator ## Prerequisites - Node.js 18+ - React 18+ - TypeScript 5+ ## Quick Start ```bash ./scripts/generate-component.sh MyComponent # Creates: # - src/components/MyComponent/MyComponent.tsx # - src/components/MyComponent/MyComponent.test.tsx # - src/components/MyComponent/MyComponent.stories.tsx # - src/components/MyComponent/index.ts

Step-by-Step Guide

1. Run Generator

▼
bash
复制代码
./scripts/generate-component.sh ComponentName

2. Choose Template

  • Basic: Simple functional component
  • With State: useState hooks
  • With Context: useContext integration
  • With API: Data fetching component

3. Customize

Edit generated files in src/components/ComponentName/

Templates

See resources/templates/ for available component templates.

▼
text
复制代码
--- ## Learn More ### Official Resources - [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) - [GitHub Skills Repository](https://github.com/anthropics/skills) - [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code) ### Community - [Skills Marketplace](https://github.com/anthropics/skills) - Browse community skills - [Anthropic Discord](https://discord.gg/anthropic) - Get help from community ### Advanced Topics - Multi-file skills with complex navigation - Skills that spawn other skills - Integration with MCP tools - Dynamic skill generation --- **Created**: 2025-10-19 **Version**: 1.0.0 **Maintained By**: agentic-flow team **License**: MIT
效率工具
文档处理
数据与分析

快捷安装

复制到终端去安装 Skill

npxskillsaddruvnet/claude-flow--skill"skill-builder"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。
cloud-scheduler-job-creator
自动处理 Google Cloud Platform 中的云调度任务创建,提供符合最佳实践的配置方案与生产级代码生成,支持计算、存储、大数据及机器学习服务的集成部署。
planning-with-files
通过创建任务计划、笔记与交付文件三个持久化文档,实现对复杂任务的结构化管理。在多阶段工作中保持目标清晰,动态更新进度并沉淀研究过程,适用于需长期跟踪的规划、研究及创作场景。