2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

「生成AI開発の珍プレー好プレー大賞！（珍プレー多め）」
@Dinn(Hongbo D)

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

2
Posted at

はじめに

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でトークン効率を維持しながら、既存のツールシステムと共存できる形を目指しました。

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

2
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?