AIエージェントのスキルを書くのに最適な人が、YAMLを書けない問題

「AIエージェントにスキルを覚えさせたいけど、設定ファイルって結局エンジニアじゃないと無理なの？」そんな疑問、持ったことありませんか？

実は今、海外の開発コミュニティでこの問題がじわじわと話題になっています。「エージェントのスキルを書くのに最適な人が、YAMLを書けない」というジレンマです。🤔

Contents

どういうこと？問題の本質をざっくり解説
「実際の業務を知っている人」がコードを書けない問題
じゃあ、どう解決するの？
- ① 非エンジニアが編集できるUI層を作る
- ② スキル定義をAI自身に書かせる
まとめ

どういうこと？問題の本質をざっくり解説

AI agent workflow / Photo by MART PRODUCTION via Pexels

AIエージェントに「スキル（Skill）」を持たせるとき、多くのフレームワークではこんな構成をとります。

# .claude/skills/customer-support.md のイメージ
---
name: customer-support
description: 顧客からの問い合わせに対応するスキル
triggers:
  - キャンセルしたい
  - 返金してほしい
output: structured
---

## 手順
1. 顧客の感情をまず受け止める
2. 問題の詳細を確認する
3. 該当するポリシーに照らして回答する

ポイントをまとめるとこんな感じです。

ファイルは .claude/skills/ などに置く
上部にYAMLで「メタ情報（名前・説明・トリガー）」を書く
下部にMarkdownで「実際の手順・ロジック」を書く
このファイルをGitリポジトリで管理する

一見シンプルに見えますよね。でも、ここに大きな落とし穴があるんです。

「実際の業務を知っている人」がコードを書けない問題

たとえば、カスタマーサポートのスキルを作る場合を考えてみましょう。

業務フローを一番よく知っているのは誰か？　それは現場のサポート担当者です。でも、サポート担当者はYAMLのフォーマットも、Gitのコミットも知らないことが多い。

一方、YAMLを書けるエンジニアは、業務の細かいニュアンスを知らないことが多い。

結果として、エンジニアが「なんとなく動くスキル」を書き、現場の知恵が反映されないまま微妙なエージェントが量産されてしまう…というわけです。😅

じゃあ、どう解決するの？

このギャップを埋めるアプローチとして、いくつかの方向性が考えられています。

① 非エンジニアが編集できるUI層を作る

バックエンドはYAMLのままでも、フロント側にGUIエディタを用意して、現場担当者がフォームを埋めるだけでスキルファイルが自動生成される仕組みにするアプローチです。

import yaml

def generate_skill_yaml(name: str, description: str, triggers: list[str]) -> str:
    """フォーム入力からSKILL.mdのYAMLヘッダーを自動生成"""
    skill_data = {
        "name": name,
        "description": description,
        "triggers": triggers,
        "output": "structured"
    }
    # YAMLフロントマターとして出力
    return f"---\n{yaml.dump(skill_data, allow_unicode=True, default_flow_style=False)}---\n"

# 現場担当者がフォームで入力した内容を変換
result = generate_skill_yaml(
    name="customer-support",
    description="顧客からの問い合わせに対応するスキル",
    triggers=["キャンセルしたい", "返金してほしい"]
)
print(result)