Skill Builder

スキルビルダー

このスキルでできること

適切な YAML フロントマター、段階的開示アーキテクチャ、完全な file$folder 構造を備えた、本番環境で使える Claude Code スキルを作成します。このスキルでは、Claude があらゆる環境（Claude.ai、Claude Code、SDK、API）で自律的に見つけて使用できるスキルの作成方法を説明します。

前提条件

• Claude Code 2.0+ または Skills に対応した Claude.ai
• Markdown と YAML の基本的な理解
• テキストエディターまたは IDE

クイックスタート

最初のスキルを作成する

# 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

---

完全な仕様

📋 YAML フロントマター（必須）

すべての SKILL.md は、必須フィールドを正確に 2 つ含む 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
---

フィールド要件

name（必須）：

• 型：文字列
• 最大長：64 文字
• 形式：人にとって分かりやすい表示名
• 用途：スキル一覧や UI に表示され、Claude のシステムプロンプトに読み込まれます
• ベストプラクティス：タイトルケースを使い、簡潔で分かりやすい名前にします
• 例：
  • ✅ "API Documentation Generator"
  • ✅ "React Component Builder"
  • ✅ "Database Schema Designer"
  • ❌ "skill-1"（説明的ではありません）
  • ❌ "This is a very long skill name that exceeds sixty-four characters"（長すぎます）

description（必須）：

• 型：文字列
• 最大長：1024 文字
• 形式：プレーンテキストまたは最小限の Markdown
• 内容：以下を必ず含めます。
  1. スキルが何をするか（機能）
  2. Claude がいつ呼び出すべきか（起動条件）
• 用途：自律的な照合のため、Claude のシステムプロンプトに読み込まれます
• ベストプラクティス：重要な起動キーワードを先に記載し、ユースケースを具体的にします
• 例：
  • ✅ "Express.js のルートから OpenAPI 3.0 のドキュメントを生成します。API ドキュメントの作成、エンドポイントの文書化、API 仕様の構築に使用します。"
  • ✅ "TypeScript、フック、テストを含む React の関数コンポーネントを作成します。新しいコンポーネントのひな形を作成するときや、クラスコンポーネントを変換するときに使用します。"
  • ❌ "API ドキュメントに関する包括的なガイド"（「いつ」の条件がありません）
  • ❌ "ドキュメントツール"（曖昧すぎます）

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

重要：Claude が使用するのは name と description のみです。その他のフィールドは無視されます。

---

📂 ディレクトリ構造

最小構成のスキル（必須）

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

重要：スキルは ~/.claude$skills/[skill-name]/ の直下に配置する必要があります。 Claude Code は、入れ子になったサブディレクトリや名前空間には対応していません！

フル機能のスキル（推奨）

~/.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

スキルの配置場所

個人用スキル（すべてのプロジェクトで使用可能）：

~/.claude$skills/
└── [your-skills]/

• パス：~/.claude$skills/ または $HOME/.claude$skills/
• スコープ：このユーザーのすべてのプロジェクトで使用可能
• バージョン管理：Git にコミットされません（リポジトリの外部）
• ユースケース：個人の生産性向上ツール、カスタムワークフロー

プロジェクト用スキル（チームで共有、バージョン管理対象）：

<project-root>/.claude$skills/
└── [team-skills]/

• パス：プロジェクトルート内の .claude$skills/
• スコープ：このプロジェクト内でのみ使用可能
• バージョン管理：Git にコミットすることを推奨します
• ユースケース：チームのワークフロー、プロジェクト固有のツール、共有ナレッジ

---

🎯 段階的開示アーキテクチャ

Claude Code では、コンテキストの負荷を増やさずに 100 個以上のスキルに対応するため、3 段階の段階的開示システムを使用します。

レベル 1：メタデータ（名前＋説明）

読み込みタイミング：Claude Code の起動時に常に読み込まれます サイズ：スキルあたり約 200 文字 目的：スキルの自律的な照合を可能にします コンテキスト：すべてのスキルについてシステムプロンプトに読み込まれます

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

レベル 2：SKILL.md 本文

読み込みタイミング：スキルが起動$matched されたとき サイズ：通常約 1～10 KB 目的：主な指示と手順 コンテキスト：アクティブなスキルについてのみ読み込まれます

# API Builder

## What This Skill Does
[Main instructions - loaded only when skill is active]

## Quick Start
[Basic procedures]

## Step-by-Step Guide
[Detailed instructions]

レベル 3 以降：参照ファイル

読み込みタイミング：Claude が参照先をたどる際に、必要に応じて読み込まれます サイズ：可変（KB～MB） 目的：詳細なリファレンス、例、スキーマ コンテキスト：Claude が特定のファイルにアクセスしたときのみ読み込まれます

# 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

メリット：約 6 KB のコンテキストで 100 個以上のスキルをインストールできます。コンテキストに入るのは、アクティブなスキルの内容（1～10 KB）のみです。

---

📝 SKILL.md のコンテンツ構成

推奨する 4 レベル構成

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

一般的なシナリオ

1. シナリオ 1: 方法...
2. シナリオ 2: 方法...

---

レベル 3：詳細な手順（詳細な作業向け）

手順ガイド

ステップ 1：初期設定

# Commands

期待される出力：

Success message

ステップ 2：設定

• 設定オプション 1
• 設定オプション 2

ステップ 3：実行

• メインコマンドを実行する
• 結果を確認する

高度なオプション

オプション 1：カスタム設定

# Advanced usage

オプション 2：統合

# Integration steps

---

レベル 4：リファレンス（ほとんどの場合は不要）

トラブルシューティング

問題：よくある問題

症状：表示される内容 原因：発生する理由 解決策：修正方法

# Fix command

問題：別の問題

解決策：解決する手順

API リファレンス全体

API_REFERENCE.md を参照してください

例

examples/ を参照してください

関連するスキル

• 関連スキル 1
• 関連スキル 2

リソース

• 外部リンク 1
• ドキュメント

---

### 🎨 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."

トリガー条件を含める：

# ✅ 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."

具体的に記述する：

# ✅ 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."

段階的な情報開示の書き方

レベル 1 は簡潔にする（概要）：

## What This Skill Does
Creates production-ready React components with TypeScript, hooks, and tests in 3 steps.

レベル 2 は一般的な手順向けにする（クイックスタート）：

## Quick Start
```bash
# Most common use case (80% of users)
generate-component MyComponent

**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]

レベル 4 は例外的なケース向けにする（リファレンス）：

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

---

🛠️ スクリプトとリソースの追加

Scripts ディレクトリ

目的：Claude が実行できるスクリプト 場所：スキルディレクトリ内の scripts/ 使用方法：SKILL.md から参照します

例：

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

SKILL.md からの参照：

## Setup
Run the setup script:
```bash
.$scripts$setup.sh

検証

設定を検証します：

node scripts$validate.js config.json

#### 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

SKILL.md からの参照：

## Templates
Use the component template:
```bash
cp resources$templates$component.tsx.template src$components/MyComponent.tsx

例

resources$examples/ にある動作する例を参照してください：

• basic-example/ - シンプルなコンポーネント
• advanced-example/ - フックとコンテキストを使用

---

### 🔗 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.

相対ファイルパス

Use the template located at `resources$templates$api-template.js`
See examples in `resources$examples$basic-usage/`

ファイル内容のインライン記述

## Example Configuration
See `resources$examples$config.json`:
```json
{
  "option": "value"
}

**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

手順ガイド

ステップ 1：セットアップ

[手順]

ステップ 2：使用方法

[手順]

ステップ 3：確認

[手順]

トラブルシューティング

• 問題：問題の説明
  • 解決策：修正方法の説明

### 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

設定

config.json を編集します：

{
  "option1": "value1",
  "option2": "value2"
}

手順ガイド

基本的な使用方法

[80% のケースで使用する手順]

高度な使用方法

[複雑なシナリオ向けの手順]

利用可能なスクリプト

• scripts$setup.sh - 初期設定
• scripts$generate.sh - コード生成
• scripts$validate.sh - 検証

リソース

• テンプレート：resources$templates/
• 例：resources$examples/

トラブルシューティング

[よくある問題と解決策]

### 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

初回使用

.$scripts$quickstart.sh

期待される出力：

✓ Setup complete
✓ Configuration validated
→ Ready to use

---

設定

基本設定

config.json を編集します：

{
  "mode": "production",
  "features": ["feature1", "feature2"]
}

高度な設定

設定ガイド を参照してください

---

手順ガイド

1. 初期設定

[詳細な手順]

2. コアワークフロー

[主な手順]

3. 統合

[統合の手順]

---

高度な機能

機能 1：カスタムテンプレート

.$scripts$generate.sh --template custom

機能 2：バッチ処理

.$scripts$batch.sh --input data.json

機能 3：CI/CD 統合

CI/CD ガイド を参照してください

---

スクリプトリファレンス

スクリプト	目的	使用方法
install.sh	依存関係をインストール	.$scripts$install.sh
generate.sh	コードを生成	.$scripts$generate.sh [name]
validate.sh	出力を検証	.$scripts$validate.sh
deploy.sh	環境にデプロイ	.$scripts$deploy.sh [env]

---

リソース

テンプレート

• resources$templates$basic.template - 基本テンプレート
• resources$templates$advanced.template - 高度なテンプレート

例

• resources$examples$basic/ - シンプルな例
• resources$examples$advanced/ - 複雑な例
• resources$examples$integration/ - 統合の例

スキーマ

• resources$schemas$config.schema.json - 設定スキーマ
• resources$schemas$output.schema.json - 出力の検証

---

トラブルシューティング

問題：インストールに失敗する

症状：install.sh の実行中にエラーが発生します 原因：依存関係が不足しています 解決策：

# Install prerequisites
npm install -g required-package
.$scripts$install.sh --force

問題：検証エラー

症状：検証スクリプトが失敗します 解決策：トラブルシューティングガイドを参照してください

---

API リファレンス

API ドキュメントの全文：API_REFERENCE.md

関連スキル

• 関連スキル 1
• 関連スキル 2

リソース

• 公式ドキュメント
• GitHub リポジトリ
• コミュニティフォーラム

---

作成日：2025-10-19 カテゴリー：上級 難易度：中級 所要時間：15-30 分

---

## 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

カスタマイズ

生成前に resources$templates$sections/ のセクションを編集してください。

### 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

ステップごとのガイド

1. ジェネレーターを実行する

.$scripts$generate-component.sh ComponentName

2. テンプレートを選択する

• 基本：シンプルな機能コンポーネント
• ステート付き：useState フック
• コンテキスト付き：useContext の統合
• API 付き：データ取得コンポーネント

3. カスタマイズする

生成されたファイルを src$components/ComponentName/ で編集してください。

テンプレート

利用可能なコンポーネントテンプレートについては、resources$templates/ を参照してください。

---

## 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