qe-skill-builder

スキルビルダー

このスキルでできること

適切な YAML フロントマター、段階的開示アーキテクチャ、完全なファイル／フォルダー構成を備えた、本番環境で使える 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 の本文

読み込み時：スキルが起動／照合されたとき サイズ：通常は約 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. テンプレートを選択する

• 基本：シンプルな機能コンポーネント
• State 付き：useState フック
• Context 付き：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