Back to Details

claude-skill-creator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Skill Creator Guide

Claude Skill Creator Guide

スキル作成のガイド。Claude Codeの機能を拡張するスキルを効果的に作成する方法を説明。
A guide for creating skills. Explains how to effectively create skills that extend the functionality of Claude Code.

When to Use This Skill

When to Use This Skill

  • 新規スキルを作成する時
  • 既存スキルを更新・改善する時
  • スキルが正しく発動しない問題を調査する時
  • ドキュメントをスキル形式に変換する時
  • When creating a new skill
  • When updating or improving an existing skill
  • When troubleshooting issues where a skill doesn't activate correctly
  • When converting documentation into skill format

What Are Skills?

What Are Skills?

スキルはClaudeの機能を拡張するフォルダ構造。モデル自動発見—Claudeがリクエストに基づいて自動的に使用を判断する（スラッシュコマンドとは異なり明示的な呼び出し不要）。
Skills are folder structures that extend Claude's functionality. Auto-discovery by the model—Claude automatically decides to use them based on user requests (no explicit invocation required, unlike slash commands).

Directory Structure

Directory Structure

Personal:  ~/.claude/skills/skill-name/SKILL.md
Project:   .claude/skills/skill-name/SKILL.md
Plugin:    パッケージに同梱
Personal:  ~/.claude/skills/skill-name/SKILL.md
Project:   .claude/skills/skill-name/SKILL.md
Plugin:    Bundled with the package

Creating a New Skill

Creating a New Skill

Step 1: ディレクトリ作成

Step 1: Create the directory

bash
mkdir -p .claude/skills/my-skill-name
bash
mkdir -p .claude/skills/my-skill-name

Step 2: SKILL.md作成（YAML frontmatter必須）

Step 2: Create SKILL.md (YAML frontmatter required)

yaml
---
name: skill-identifier          # 必須: 小文字/数字/ハイフンのみ、64文字以内
description: 何をするか + いつ使うか  # 必須: 1024文字以内、トリガーキーワード含む
allowed-tools: Read, Grep, Edit  # オプション: ツール制限
---
name規則:
  • 小文字、数字、ハイフンのみ
  • 64文字以内
  • 例: 
    api-docs-writer
    , 
    db-migration-helper
description規則:
  • 「何をするか」+「いつ使うか」を両方含める
  • トリガーキーワードを含める
  • 1024文字以内
yaml
undefined
yaml
---
name: skill-identifier          # Required: Only lowercase letters, numbers, hyphens, max 64 characters
description: What it does + when to use it  # Required: Max 1024 characters, include trigger keywords
allowed-tools: Read, Grep, Edit  # Optional: Tool restrictions
---
Name Rules:
  • Only lowercase letters, numbers, and hyphens
  • Maximum 64 characters
  • Examples: 
    api-docs-writer
    , 
    db-migration-helper
Description Rules:
  • Include both "what it does" and "when to use it"
  • Include trigger keywords
  • Maximum 1024 characters
yaml
undefined

✅ GOOD

✅ GOOD

description: E2Eテストの作成・デバッグ・失敗修正を支援。Playwrightテスト失敗時、新規テスト作成時に使用。
description: Assists with creating, debugging, and fixing failed E2E tests. Used when Playwright tests fail or when creating new tests.

❌ BAD

❌ BAD

description: テストを手伝う
undefined
description: Helps with tests
undefined

Step 3: 本文の推奨構造

Step 3: Recommended Body Structure

markdown
undefined
markdown
undefined

Skill Title

Skill Title

概要（1-2文）
Overview (1-2 sentences)

When to Use This Skill

When to Use This Skill

  • シナリオ1
  • シナリオ2
  • Scenario 1
  • Scenario 2

Instructions

Instructions

  1. Step 1: 最初にやること
  2. Step 2: 次にやること
  3. Step 3: 最後にやること
  1. Step 1: First thing to do
  2. Step 2: Next thing to do
  3. Step 3: Final thing to do

Examples

Examples

Example 1: [シナリオ]

Example 1: [Scenario]

[コード例]
[Code example]

Troubleshooting

Troubleshooting

Issue: 問題 Solution: 解決方法
Issue: Problem Solution: Resolution

AI Assistant Instructions

AI Assistant Instructions

このスキルが有効化された時:
  1. まず○○を確認
  2. 次に○○を実行
Always:
  • 常に○○する
Never:
  • ○○しない
undefined
When this skill is activated:
  1. First, check ○○
  2. Next, execute ○○
Always:
  • Always ○○
Never:
  • Never ○○
undefined

Optional: ツール制限

Optional: Tool Restrictions

yaml
allowed-tools: Read, Grep, Glob  # 読み取り専用
yaml
allowed-tools: Read, Grep, Glob  # Read-only

Optional: 補助ファイル

Optional: Supplementary Files

my-skill-name/
├── SKILL.md              # メイン（必須、500行以下）
├── reference.md          # 詳細リファレンス（必要時読み込み）
└── templates/            # テンプレート
SKILL.mdから参照:
markdown
詳細は [reference.md](reference.md) を参照。
my-skill-name/
├── SKILL.md              # Main file (required, max 500 lines)
├── reference.md          # Detailed reference (loaded when needed)
└── templates/            # Templates
Reference from SKILL.md:
markdown
For details, refer to [reference.md](reference.md).

Best Practices

Best Practices

1. スキルは1機能に絞る

1. Focus skills on a single function

yaml
undefined
yaml
undefined

✅ DO

✅ DO

  • api-docs-writer: API文書生成
  • test-strategy: テスト実装
  • api-docs-writer: API documentation generation
  • test-strategy: Test implementation

❌ DON'T

❌ DON'T

  • developer-helper: 何でも（曖昧）
undefined
  • developer-helper: Everything (vague)
undefined

2. トリガーキーワードを含める

2. Include trigger keywords

yaml
undefined
yaml
undefined

✅ GOOD

✅ GOOD

description: OpenAPI/Swagger文書をExpress/FastAPIから生成。API文書作成時に使用。
description: Generate OpenAPI/Swagger documentation from Express/FastAPI. Used when creating API documentation.

❌ BAD

❌ BAD

description: API文書を手伝う
undefined
description: Helps with API documentation
undefined

3. 具体例を提供

3. Provide concrete examples

ユーザーもClaudeも例から学ぶ。実際のコード例を含める。
Both users and Claude learn from examples. Include actual code examples.

4. AI Assistant Instructionsを明示

4. Specify AI Assistant Instructions

markdown
undefined
markdown
undefined

AI Assistant Instructions

AI Assistant Instructions

When this skill is activated:
  1. まずコードベースを分析
  2. 必要なら質問
  3. 初期バージョンを生成
Always:
  • TypeScriptで型安全に
  • エラーハンドリングを含める
Never:
  • 検証をスキップしない
undefined
When this skill is activated:
  1. First, analyze the codebase
  2. Ask questions if needed
  3. Generate an initial version
Always:
  • Use TypeScript for type safety
  • Include error handling
Never:
  • Don't skip validation
undefined

5. コンテキストウィンドウを意識

5. Be mindful of the context window

  • SKILL.mdは500行以下
  • Claudeの基礎知識は説明不要
  • 詳細は参照ファイルに分離
  • SKILL.md must be under 500 lines
  • No need to explain basic knowledge that Claude already has
  • Separate details into reference files

6. Progressive Disclosure

6. Progressive Disclosure

my-skill-name/
├── SKILL.md          # コア（< 500行）
├── reference.md      # 詳細（必要時のみ読込）
└── examples.md       # 拡張例（必要時のみ読込）
my-skill-name/
├── SKILL.md          # Core ( < 500 lines)
├── reference.md      # Details (loaded only when needed)
└── examples.md       # Extended examples (loaded only when needed)

Common Pattern: Code Generation

Common Pattern: Code Generation

yaml
---
name: component-generator
description: React/Vue/Angularコンポーネントを生成。新規コンポーネント作成時に使用。
---
yaml
---
name: component-generator
description: Generate React/Vue/Angular components. Used when creating new components.
---

Component Generator

Component Generator

Instructions

Instructions

  1. コンポーネント種別を確認（React/Vue/Angular）
  2. 名前とpropsを取得
  3. 生成: コンポーネント + テスト + Storybook
  4. プロジェクト規約に従う
undefined
  1. Confirm the component type (React/Vue/Angular)
  2. Get the name and props
  3. Generate: Component + Tests + Storybook
  4. Follow project conventions
undefined

Troubleshooting

Troubleshooting

スキルが発動しない

Skill doesn't activate

原因解決
トリガーキーワード不足descriptionに具体的キーワード追加
name形式が不正小文字/数字/ハイフンのみに修正
YAML不正
---
デリミタ確認、タブ→スペース
ファイル名が違う
SKILL.md
に統一（大文字小文字注意）
CauseSolution
Insufficient trigger keywordsAdd specific keywords to the description
Invalid name formatCorrect to use only lowercase letters, numbers, and hyphens
Invalid YAMLCheck the 
---
delimiters, replace tabs with spaces
Incorrect filenameStandardize to 
SKILL.md
(note case sensitivity)

意図しないタイミングで発動

Activates at unintended times

原因解決
descriptionが広すぎるより具体的なキーワードに変更
他スキルとキーワード重複ユニークなキーワードを使用
CauseSolution
Description is too broadChange to more specific keywords
Keyword overlap with other skillsUse unique keywords

指示に従わない

Doesn't follow instructions

原因解決
指示が曖昧番号付きステップで明示化
AI Instructions欠如セクション追加
CauseSolution
Instructions are vagueClarify using numbered steps
Missing AI InstructionsAdd the section

Team Sharing

Team Sharing

bash
undefined
bash
undefined

プロジェクトスキル

Project skills

git add .claude/skills/skill-name/ git commit -m "feat: add [skill-name] skill" git push
git add .claude/skills/skill-name/ git commit -m "feat: add [skill-name] skill" git push

チームメンバーは git pull で取得

Team members can get it with git pull

undefined
undefined

Quick Checklist

Quick Checklist

  • ディレクトリ: 
    .claude/skills/skill-name/
  • ファイル名: 
    SKILL.md
    （大文字小文字注意）
  • YAML frontmatter: 
    ---
    で囲む
  • name
    : 小文字/ハイフン、64文字以内
  • description
    : 何 + いつ、トリガーキーワード含む
  • "When to Use This Skill" セクション
  • ステップバイステップ Instructions
  • 具体的な Examples
  • AI Assistant Instructions
  • 500行以下
  • Directory: 
    .claude/skills/skill-name/
  • Filename: 
    SKILL.md
    (note case sensitivity)
  • YAML frontmatter: Enclosed with 
    ---
  • name
    : Lowercase/hyphens only, max 64 characters
  • description
    : Includes "what" + "when", with trigger keywords
  • "When to Use This Skill" section
  • Step-by-step Instructions
  • Concrete Examples
  • AI Assistant Instructions
  • Under 500 lines

AI Assistant Instructions

AI Assistant Instructions

このスキルが有効化された時:
  1. 要件確認: 新規作成か更新かを確認
  2. テンプレート提供: 上記の推奨構造に従う
  3. 検証: チェックリストで確認
Always:
  • description に「何をするか」+「いつ使うか」を含める
  • AI Assistant Instructionsセクションを含める
  • 500行以下を維持する
Never:
  • nameにアンダースコアやスペースを使用しない
  • descriptionを曖昧にしない
  • 基礎的なプログラミング概念を説明しない（Claudeは知っている）
When this skill is activated:
  1. Requirement Confirmation: Confirm whether it's a new creation or an update
  2. Provide Template: Follow the recommended structure above
  3. Validation: Verify using the checklist
Always:
  • Ensure the description includes "what it does" + "when to use it"
  • Include the AI Assistant Instructions section
  • Keep it under 500 lines
Never:
  • Don't use underscores or spaces in the name
  • Don't make the description vague
  • Don't explain basic programming concepts (Claude already knows them)