skill-creator

スキル作成者

このスキルでは、効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供して Claude の機能を拡張する、モジュール式の自己完結型パッケージです。特定の領域やタスクに関する「オンボーディングガイド」と考えてください。スキルによって、Claude は汎用エージェントから、どのモデルも完全には備えられない手順に関する知識を持つ専門エージェントへと変わります。

スキルで提供されるもの

1. 専門的なワークフロー — 特定の領域における複数ステップの手順
2. ツール連携 — 特定のファイル形式や API を扱うための指示
3. 領域の専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. バンドルされたリソース — 複雑で反復的なタスクに対応するスクリプト、リファレンス、アセット

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと、任意のバンドルされたリソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

メタデータの品質： YAML フロントマターの name と description によって、Claude がいつスキルを使用するかが決まります。スキルの機能と使用する場面を具体的に記述してください。「このスキルは、〜の場合に使用されます」のように、三人称で記述してください。

バンドルされたリソース（任意）

スクリプト（scripts/）

確実な実行や、繰り返し書き直される作業に必要な実行可能コード（Python/Bash など）です。

• 含める場合：同じコードを繰り返し書き直す場合、または確実な実行が必要な場合
• 例：PDF の回転タスク用の scripts/rotate_pdf.py
• 利点：トークンを効率よく使え、決定論的に実行でき、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整のため、Claude がスクリプトを読み込む必要がある場合もあります

リファレンス（references/）

Claude のプロセスと思考に役立てるため、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含める場合：Claude が作業中に参照すべきドキュメントがある場合
• 例：財務スキーマ用の references/finance.md、企業の NDA テンプレート用の references/mnda.md、企業ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• 用途：データベーススキーマ、API ドキュメント、領域知識、企業ポリシー、詳細なワークフローガイド
• 利点：SKILL.md を簡潔に保ち、必要だと Claude が判断したときだけ読み込めます
• ベストプラクティス：ファイルが大きい場合（10k 語超）は、SKILL.md に grep 検索パターンを記載してください
• 重複を避ける：情報は SKILL.md またはリファレンスファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核に不可欠な情報でない限り、詳細情報にはリファレンスファイルを優先してください。そうすることで、SKILL.md を簡潔に保ちつつ、コンテキストウィンドウを圧迫せずに情報を見つけやすくできます。SKILL.md には不可欠な手順の指示とワークフローのガイダンスだけを残し、詳細な参考資料、スキーマ、例はリファレンスファイルに移してください。

アセット（assets/）

コンテキストに読み込むことを目的とせず、Claude が生成する出力内で使用するファイルです。

• 含める場合：スキルで最終出力に使うファイルが必要な場合
• 例：ブランドアセット用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML/React のボイラープレート用の assets/frontend-template/、タイポグラフィ用の assets/font.ttf
• 用途：テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更するサンプルドキュメント
• 利点：出力リソースをドキュメントから分離でき、コンテキストに読み込まずに Claude がファイルを使用できます

Privacy and Path References

CRITICAL: Skills intended for public distribution must not contain user-specific or company-specific information:

• Forbidden: Absolute paths to user directories (/home/username/, /Users/username/, /mnt/c/Users/username/)
• Forbidden: Personal usernames, company names, department names, product names
• Forbidden: OneDrive paths, cloud storage paths, or any environment-specific absolute paths
• Forbidden: Hardcoded skill installation paths like ~/.claude/skills/ or /Users/username/Workspace/claude-code-skills/
• Allowed: Relative paths within the skill bundle (scripts/example.py, references/guide.md)
• Allowed: Standard placeholders (~/workspace/project, username, your-company)
• Best practice: Reference bundled scripts using simple relative paths like scripts/script_name.py - Claude will resolve the actual location

Versioning

CRITICAL: Skills should NOT contain version history or version numbers in SKILL.md:

• Forbidden: Version sections (## Version, ## Changelog, ## Release History) in SKILL.md
• Forbidden: Version numbers in SKILL.md body content and frontmatter (version: キーも置かない)
• Correct location: バージョンは配布物側 (このリポジトリでは .claude-plugin/plugin.json の version) で一元管理する
• Rationale: Marketplace infrastructure manages versioning; SKILL.md should be timeless content focused on functionality
• Example: Instead of documenting v1.0.0 → v1.1.0 changes in SKILL.md, update the plugin version only

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Skill Creation Best Practice

Anthropic has wrote skill authoring best practices, you SHOULD retrieve it before you create or update any skills, the link is https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md

⚠️ CRITICAL: Edit Skills at Source Location

NEVER edit skills in ~/.claude/plugins/cache/ - that's a read-only cache directory. All changes there are:

• Lost when cache refreshes
• Not synced to source control
• Wasted effort requiring manual re-merge

ALWAYS verify you're editing the source repository:

# WRONG - cache location (read-only copy)
~/.claude/plugins/cache/<your-marketplace>/my-skill/1.0.0/my-skill/SKILL.md

# RIGHT - source repository
/path/to/your/claude-code-skills/my-skill/SKILL.md

Before any edit, confirm the file path does NOT contain /cache/ or /plugins/cache/.

Skill Creation Process

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

• "What functionality should the image-editor skill support? Editing, rotating, anything else?"
• "Can you give some examples of how this skill would be used?"
• "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
• "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルに変えるには、各例を次のように分析します。

1. 例に一から取り組む方法を検討する
2. Claude に与える自由度の適切なレベルを判断する
3. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

タスクのリスクに応じて具体性を調整します。

• 自由度が高い（テキストによる指示）：複数の有効な方法があり、最適な進め方は状況によって異なります（例：コードレビュー、トラブルシューティング、コンテンツ分析）
• 自由度が中程度（パラメーター付きの擬似コード）：望ましいパターンはあるものの、許容できる範囲での違いがあります（例：API 統合パターン、データ処理ワークフロー）
• 自由度が低い（正確なスクリプト）：操作が壊れやすく、一貫性が非常に重要で、順序にも意味があります（例：PDF の回転、データベースのマイグレーション、フォームの検証）

例：「この PDF の回転を手伝って」のような依頼に対応する pdf-editor スキルを構築する場合、分析から次のことがわかります。

1. PDF を回転するには、毎回同じコードを書き直す必要があります
2. scripts/rotate_pdf.py スクリプトをスキル内に保存すると便利です

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」のような依頼に対応する frontend-webapp-builder スキルを設計する場合、分析から次のことがわかります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ HTML／React のボイラープレートが必要です
2. ボイラープレートとなる HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキル内に保存すると便利です

「今日ログインしたユーザーは何人ですか？」のような依頼に対応する big-query スキルを構築する場合、分析から次のことがわかります。

1. BigQuery のクエリでは、毎回テーブルスキーマとその関連性を再確認する必要があります
2. テーブルスキーマを記載した references/schema.md ファイルをスキル内に保存すると便利です

スキルに含める内容を決めるため、具体例をそれぞれ分析し、含めるべき再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成します。

ステップ 3：スキルを初期化する

ここまで来たら、実際にスキルを作成します。

開発するスキルがすでに存在し、反復やパッケージ化が必要な場合に限り、このステップを省略します。その場合は、次のステップに進みます。

新しいスキルを一から作成するときは、必ず init_skill.py スクリプトを実行します。このスクリプトを使うと、スキルに必要なものがすべて含まれた新しいテンプレートディレクトリが自動的に生成されるため、スキルの作成をより効率的かつ確実に進められます。

使い方：

scripts/init_skill.py <skill-name> --path <output-directory>

スクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO のプレースホルダーを含む SKILL.md テンプレートを生成します
• リソース用のディレクトリ例として、scripts/、references/、assets/ を作成します
• 各ディレクトリに、カスタマイズまたは削除できるサンプルファイルを追加します

初期化後、必要に応じて生成された SKILL.md とサンプルファイルをカスタマイズまたは削除します。

ステップ 4：スキルを編集する

（新しく生成したスキルでも、既存のスキルでも）編集する際は、そのスキルが別の Claude インスタンスによって使われることを念頭に置いてください。Claude にとって役立ち、すぐにはわからない情報を含めることに注力します。別の Claude インスタンスがタスクをより効果的に実行するうえで役立つ手順に関する知識、ドメイン固有の詳細、再利用可能なアセットについて検討します。

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Also, delete any example files and directories not needed for the skill. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.

When updating an existing skill: Scan all existing reference files to check if they need corresponding updates. New features often require updates to architecture, workflow, or other existing documentation to maintain consistency.

Reference File Naming

Filenames must be self-explanatory without reading contents.

Pattern: <content-type>_<specificity>.md

Examples:

• ❌ commands.md, cli_usage.md, reference.md
• ✅ script_parameters.md, api_endpoints.md, database_schema.md

Test: Can someone understand the file's contents from the name alone?

Update SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

To complete SKILL.md, answer the following questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used?
3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.

Step 5: Sanitization Review (Optional)

Ask the user before executing this step: "This skill appears to be extracted from a business project. Would you like me to perform a sanitization review to remove business-specific content before public distribution?"

Skip this step if:

• The skill was created from scratch for public use
• The user explicitly declines sanitization
• The skill is intended for internal/private use only

When to perform sanitization:

• Skill was extracted from a business/internal project
• Skill contains domain-specific examples from real systems
• Skill will be distributed publicly or to other teams

Sanitization process:

1. Load the checklist: Read references/sanitization_checklist.md for detailed guidance

2. Run automated scans to identify potential sensitive content:

   # Product/project names, person names, paths
   grep -rniE "<product-name>|<codename>|<team-name>|/Users/|/home/" skill-folder/
   
   # Chinese characters (if skill should be English-only)
   grep -rn '[一-龥]' skill-folder/
   

3. Review and replace each category:

   • Product/project names → generic terms
   • Person names → "Alice", "Bob", role-based references
   • Entity names → generic entities (ORDER, USER, PRODUCT)
   • Folder structures → generic paths
   • Internal jargon → industry-standard terms
   • Language-specific content → translate or remove

4. Verify completeness:

   • Re-run all grep patterns (should return no matches)
   • Read through skill to ensure coherence
   • Confirm skill still functions correctly

Common replacements:

Business-Specific	Generic Replacement
"Project Nimbus" (社内コードネーム)	"the project"
"Acme Reviewer Portal" (製品名)	"the application"
"Alice will handle..." (実在人名)	role-based reference ("the reviewer will handle...")
REVIEW_RESULT (社内スキーマ名)	ORDER
internal jargon ("ultrathink")	"deep review"
混入した他言語コメント	本文言語へ翻訳 or 削除

Step 6: Security Review

Before packaging or distributing a skill, run the security scanner to detect hardcoded secrets and personal information:

# Required before packaging
python scripts/security_scan.py <path/to/skill-folder>

# Verbose mode includes additional checks for paths, emails, and code patterns
python scripts/security_scan.py <path/to/skill-folder> --verbose

Detection coverage:

• Hardcoded secrets (API keys, passwords, tokens) via gitleaks
• Personal information (usernames, emails, company names) in verbose mode
• Unsafe code patterns (command injection risks) in verbose mode

First-time setup: Install gitleaks if not present:

# macOS
brew install gitleaks

# Linux/Windows - see script output for installation instructions

Exit codes:

• 0 - Clean (safe to package)
• 1 - High severity issues
• 2 - Critical issues (MUST fix before distribution)
• 3 - gitleaks not installed
• 4 - Scan error

Remediation for detected secrets:

1. Remove hardcoded secrets from all files
2. Use environment variables: os.environ.get("API_KEY")
3. Rotate credentials if previously committed to git
4. Re-run scan to verify fixes before packaging

Step 7: Packaging a Skill

Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:

scripts/package_skill.py <path/to/skill-folder>

Optional output directory specification:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script will:

1. Validate the skill automatically, checking:

   • YAML frontmatter format and required fields
   • Skill naming conventions and directory structure
   • Description completeness and quality
   • Path reference integrity - all scripts/, references/, and assets/ paths mentioned in SKILL.md must exist

2. Package the skill if validation passes, creating a zip file named after the skill (e.g., my-skill.zip) that includes all files and maintains the proper directory structure for distribution.

Common validation failure: If SKILL.md references scripts/my_script.py but the file doesn't exist, validation will fail with "Missing referenced files: scripts/my_script.py". Ensure all bundled resources exist before packaging.

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

Step 8: Update Distribution Metadata

このリポジトリの marketplace は single-plugin 構成 (.claude-plugin/marketplace.json は plugin 一覧のみ、per-skill エントリは持たない)。skill を追加/更新したら:

1. skill 数の記載を更新: README.md と docs/adoption.md の「skills N 本」を実数に合わせる
2. plugin バージョンを bump: .claude-plugin/plugin.json の version を semver で上げる
   • Patch (0.1.x): Bug fixes, typo corrections
   • Minor (0.x.0): New skills, new features, additional references
   • Major (x.0.0): Breaking changes, restructured workflows
3. lint を通す: uv run python scripts/lint_skills.py --dir skills (frontmatter スキーマ検証)

.claude-plugin/marketplace.json に per-skill の version/category/keywords/skills[] を追加してはいけない (この kit のスキーマではない)。

Step 9: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

Refinement filter: Only add what solves observed problems. If best practices already cover it, don't duplicate.