Claude Skillsのコンセプトを自分のAgentプロジェクトに導入しました

はじめに

2025年10月にAnthropicがClaude Skillsをリリースした際、その設計思想に興味を持ちました。

自分が開発しているAgentでは、従来のツールシステム（コードベース）を採用していましたが、より柔軟な拡張方法が欲しいと感じていました。特に、非エンジニアでも簡単に機能を追加できる仕組みや、チーム内で知識を共有しやすい形式が必要だと考えていました。

本記事では、Claude Skillsの設計コンセプトを参考に、実際に自分のプロジェクトへ導入した経験を共有します。
https://www.anthropic.com/news/skills

Claude Skillsとは

Anthropic公式のドキュメントによると：

Agent Skills package expertise into discoverable capabilities. Each Skill consists of a SKILL.md file with instructions that Claude reads when relevant, plus optional supporting files.

つまり、Skillsは「専門知識をパッケージ化した、発見可能な機能」です。
公式が強調している4つの特性があります：

• Composable: 複数のSkillsが協調して動作する
• Portable: Claude Apps、Claude Code、APIで統一の形式を使用
• Efficient: 必要な時に必要なものだけを読み込む
• Powerful: 実行可能なコードを含めることができる

基本構造

Skillは次のような構造を持ちます：

skill-name/
├── SKILL.md       （必須）
├── reference.md   （任意）
└── scripts/       （任意）

SKILL.mdファイルはYAMLフロントマターとMarkdown本文で構成されます：

---
name: skill-name
description: このSkillの説明と使用タイミング
allowed-tools: "Read,Grep,Glob"
---

# Skillの詳細な指示

ここにLLMが従うべき具体的な手順や例を記述します。

必須フィールドはnameとdescriptionのみです。allowed-toolsを指定すると、そのSkillが使用できるツールを制限できます。

Model-invoked設計

重要な点として、Skillsはmodel-invoked（モデルが呼び出す）方式です。これはスラッシュコマンド（user-invoked）とは異なり、Claudeがリクエストの内容とSkillの説明を基に、自律的に使用を判断します。

Claude公式アプリケーションでは、次のようにSkillsが管理されます：

Settingsから各Skillを有効化/無効化でき、必要に応じてカスタムSkillをアップロードすることも可能です。

導入アプローチ

設計方針

既存のツールシステムを完全に置き換えるのではなく、Skillsのコンセプトを追加の拡張機能として統合することにしました。

確定的な処理（データ変換、API呼び出しなど）はコードツールが最適である一方、柔軟な処理（コンテンツ生成、レビューなど）はプロンプトベースが便利です。両方をサポートすることで幅広いユースケースに対応できると考えました。

アーキテクチャ

実装の全体像は次のようになります：

Agentプロジェクト
├── tools/              （既存：コードベースのツール）
│   ├── data-processor.js
│   └── api-client.js
│
└── skills/             （新規：Skillsベース）
    ├── code-reviewer/
    │   └── SKILL.md
    └── content-writer/
        ├── SKILL.md
        └── templates/

実装の流れ

1. SKILL.mdパーサーの実装

まず、SKILL.mdファイルを解析する機能を作ります：

import fs from 'fs';
import matter from 'gray-matter';

function parseSkillFile(skillPath) {
  const content = fs.readFileSync(skillPath, 'utf-8');

  // YAMLフロントマターとMarkdownを分離
  const { data, content: markdown } = matter(content);

  return {
    name: data.name,
    description: data.description,
    prompt: markdown,  // 詳細な指示
    allowedTools: data['allowed-tools']?.split(',').map(s => s.trim()),
    model: data.model
  };
}

2. Skill発見機能

プロジェクト内のSkillsを自動的に発見します：

function discoverSkills(projectRoot) {
  const skillsDir = path.join(projectRoot, 'skills');

  if (!fs.existsSync(skillsDir)) {
    return [];
  }

  const skills = [];
  const dirs = fs.readdirSync(skillsDir);

  for (const dir of dirs) {
    const skillMdPath = path.join(skillsDir, dir, 'SKILL.md');

    if (fs.existsSync(skillMdPath)) {
      const skill = parseSkillFile(skillMdPath);
      skill.path = path.join(skillsDir, dir);
      skills.push(skill);
    }
  }

  return skills;
}

3. エージェントシステムへの統合

発見したSkillsをどう使うかは、Agentシステムの設計次第です。一般的なアプローチとして、Skillのプロンプトを会話履歴に注入する方法があります：

async function activateSkill(skill, userRequest) {
  // Skillのプロンプトをシステムメッセージとして追加
  const systemMessage = {
    role: 'system',
    content: skill.prompt
  };

  // 既存の会話履歴にSkillの指示を追加
  const messages = [
    systemMessage,
    ...conversationHistory,
    { role: 'user', content: userRequest }
  ];

  // LLMに送信
  const response = await callLLM(messages);
  return response;
}

この実装例はあくまで概念的なものです。実際にはAgentフレームワークのAPIに合わせて調整する必要があります。

4. Progressive Disclosureの実装

Claude Skillsの重要な設計原則である「Progressive Disclosure」（段階的な情報開示）を実装します：

// 第1層：起動時にメタデータのみ読み込み
const skillsMetadata = skills.map(s => ({
  name: s.name,
  description: s.description
}));

// 第2層：Skill使用時に完全なプロンプトを読み込み
function loadFullSkill(skillName) {
  const skill = skills.find(s => s.name === skillName);
  return skill.prompt;  // SKILL.mdの本文
}

// 第3層：必要に応じて参照ファイルを読み込み
function loadReference(skillPath, refName) {
  const refPath = path.join(skillPath, 'references', refName);
  return fs.readFileSync(refPath, 'utf-8');
}

使用例

Skillの作成

実際にSkillを作成する例です：

---
name: code_reviewer
description: コードレビューを行い、バグやベストプラクティス違反を指摘する
allowed-tools: "Read,Grep,Glob"
---

# コードレビューガイド

あなたはコードレビューの専門家です。

## レビュー手順

1. 対象ファイルを読み取る
2. 次の観点で分析する：
   - セキュリティ脆弱性（SQLインジェクション、XSSなど）
   - パフォーマンス問題
   - コード品質（重複、複雑度など）

## 出力形式

問題を発見した場合、次の形式で報告してください：

- **種類**: security/performance/quality
- **重要度**: high/medium/low
- **場所**: ファイル名:行番号
- **説明**: 具体的な問題内容
- **推奨**: 修正方法の提案

使用方法

Skillsを登録すると、Agentが自動的に適切なタイミングで使用します：

// プロジェクトのSkillsを発見して登録
const skills = discoverSkills(process.cwd());
registerSkillsAsTools(skills, toolRegistry);

// 後はAgentが自動的に判断
// ユーザー: "auth.jsをレビューしてください"
// Agent: code_reviewer Skillを使用することを判断 → 実行

実際に使ってみて

いくつかのユースケースで試してみました。

次は実際にSkillが動作している様子です：

カスタマーサービス対応のシナリオで、customer-service-expert Skillが自動的に有効化され、専門的な対応方法やテンプレートを活用しています。

柔軟な判断が必要なタスク（コードレビュー、コンテンツ生成など）では、Markdownで手順を記述できるSkillsのアプローチが便利でした。チームメンバーが専門知識をSkillとして共有しやすくなりました。

一方で、確定的なデータ処理などは従来のコードツールのほうが安定しています。両方を使い分けることで、それぞれの長所を活かせると感じています。

まとめ

Claude Skillsの設計思想を参考に、既存のAgentプロジェクトへ統合する方法を紹介しました。

SKILL.mdという標準化された形式で知識をパッケージ化し、Progressive Disclosureでトークン効率を維持しながら、既存のツールシステムと共存できる形を目指しました。

この実装はあくまで一つのアプローチです。プロジェクトの特性やチームの要件によって、最適な方法は異なると思います。興味があれば、自分のプロジェクトでも試してみてください。