TRIAL＆RetailAI Advent Calendar 2025

Quarkus+Kotlin開発向けAgentSkillsを作ってみた。プロジェクト生成+エラー分析スキル

Last updated at 2025-12-20Posted at 2025-12-20

はじめに

こんにちは、@akaitigoです。

この記事は TRIAL&RetailAI Advent Calendar 2025の21日目の記事です。

昨日は@inuverse44さんの「少しだけ背伸びして理解するJPEG」でした。
JPEG圧縮の原理、人間の視覚に踏み込んだ濃い内容です。

この記事ではAgentSkillsについての説明、2つのSkill(プロジェクトの生成、エラーの解消)を作成して分かった現状について書きます。

この記事でわかること:

AgentSkillsとは何か、Skillの構成
Quarkus+Kotlin向けに作った2つのSkills（プロジェクト生成、エラー解決
導入方法と動作イメージ
AgentSkillsを作ってみて感じた良い点、課題

前提）AgentSkillsとは

AgentSkillsでは、AIエージェントに「手順・知識・リソース」を追加することが出来ます。
スキルはフォルダ単位で表現され、必要なときに読み込まれるように設計されています。

ディレクトリ構造

AgentSkillsの最小構成は1つのディレクトリ+SKILL.md だけです。必要に応じてscripts/・references/・assets/を追加します。

skill-name/
└── SKILL.md          # 必須
    (optional)
    ├── scripts/      # 実行可能な手順（bash/python など）
    ├── references/   # 追加の技術資料・手順
    └── assets/       # テンプレートや静的ファイル

ClaudeCodeでは起動時にはname/descriptionだけを読み、スキルが発火した時点でSKILL.md本文を読み込み、必要になったらreferences/やscripts/を参照する、という流れで利用されています。これによりコンテキスト消費を抑えつつ、スキルを利用することが出来ます。

MCP/AGENTS.mdとの比較（ざっくり）

観点	AgentSkills	MCP	AGENTS.md
目的	スキル単位で手順・知識・素材をパッケージ化	ツール/リソース/プロンプトを提供・取得するためのプロトコル	リポジトリのルール等の情報を「エージェント用のREADME」として提示
単位	`skill-name/`ディレクトリ	ローカル/リモートのサービス	リポジトリ直下（必要ならサブディレクトリにネスト）
主な構成要素	`SKILL.md`+optional dirs	Tools/Resources/Prompts	Markdown

Skillsの優位性

再利用性/配布性:スキルはフォルダ単位で持ち運べ、複数のスキル対応エージェントで再利用できる前提の設計。
コンテキスト効率:段階的に読み込むことにより、普段はメタ情報だけを読み、必要時だけ詳細をロードできる。
粒度の適切さ:MCPが「外部連携の規格」、AGENTS.mdが「一定の粒度(プロジェクト全体等)のルール」なのに対し、AgentSkillsは「タスク/ドメインの手順」を切り出せる。

参考:

作成したSkill

Quarkus+Kotlin開発で、プロジェクトの作成とエラーの原因特定を短縮する2つのSkillsを作成しました。

1. quarkus-project-generator

QuarkusCLIを使ってプロジェクトを生成し、Kotlin特有のパターンを適用します。
今回は単純なプロジェクトの生成を一定の手順で行わせれる事まで行いましたが、モノリポのプロジェクトでサービスを追加していく際の手順にSkillを合わせて効率化とかも行えそうだと思えました。
今振り返るとapplication.propertiesを、テンプレートとしてassets/に置いても良かったと思えます。

対応パターン:

RESTAPI（デフォルト）
Reactive
GraphQL

使用例:
下記のような明確なプロンプトでも可能ですが、単に~~サービスを作成してといった指示でもAIエージェント側から質問を行いプロジェクトを作成することが出来ました。

「Quarkus+KotlinのRESTAPIプロジェクトを作成して」
「order-serviceという名前でReactiveパターンのQuarkusアプリを生成して」

適用される設定:

KotlinPanacheEntityにcompanion object : PanacheCompanion<Entity>を追加
application.properties の推奨設定（Dev Services、ログ設定など）

2. quarkus-error-solver

Quarkusアプリケーションのエラーを解析し、原因の要約と修正手順、必要なら差分例まで提示します。

対応エラーカテゴリ:

カテゴリ	例
CDI/DI	`UnsatisfiedResolutionException`,`AmbiguousResolutionException`
データベース	接続エラー,`EntityNotFoundException`,`TransactionRequiredException`
REST/HTTP	JSONシリアライズ,CORS, 404 Not Found
Nativeビルド	Reflection設定不足,リソースファイル不足
DevServices	Docker未起動,ポート競合
Kotlin固有	`lateinit`未初期化,finalクラスのプロキシ問題

例:

jakarta.enterprise.inject.UnsatisfiedResolutionException:
Unsatisfied dependency for type [SomeService] and qualifiers [@Default]

ターミナルにエラーが出たことをトリガーに、その場で原因と対処を返します。
Kotlinのコンパイルエラー（例:Unresolved reference 'listAll'）もトリガー対象です。

Skillsの構成（主要部分）

※ 例では主要ディレクトリのみ抜粋しています（動作テストに利用したexamples/などは省略）

claude-skills-quarkus/
├── .claude-plugin/
│   ├── plugin.json         # プラグインマニフェスト
│   └── marketplace.json    # マーケットプレイス定義
├── skills/
│   ├── quarkus-project-generator/
│   │   ├── SKILL.md                    # Skill定義
│   │   └── references/
│   │       ├── kotlin-panache.md       # Panache パターン集
│   │       └── application-config.md   # 設定テンプレート
│   └── quarkus-error-solver/
│       ├── SKILL.md                    # Skill定義
│       └── references/
│           └── ERROR_PATTERNS.md       # エラーパターン集
└── README.md

SKILL.md の構造

---
name: quarkus-error-solver
description: |
  Quarkusアプリケーションのエラーを分析し解決策を提供する。CDI/DI、データベース、REST/HTTP、Nativeビルド、Kotlin固有のエラーをカバー。...
license: MIT
---

# Quarkus Error Solver

Quarkus + Kotlin アプリケーションのエラーを診断・解決する。

## 自動検出

ターミナル出力でQuarkus関連エラー（ビルドログ、ランタイム例外）を検出した場合、ユーザーのリクエストを待たずに自動的にこのスキルを適用する。

**トリガーパターン:**
- `./gradlew build` または `./gradlew quarkusDev` からのスタックトレースを含むビルド失敗
- スタックトレースに含まれるキーワード: `jakarta.enterprise`, `io.quarkus`, ...
- エラーキーワード: `UnsatisfiedResolutionException`, `AmbiguousResolutionException`, ...
- Kotlin固有: `not proxyable because it's final`, `lateinit property not initialized`, ...

## クイックスタート

1. エラーメッセージまたはスタックトレースを貼り付ける
2. [ERROR_PATTERNS.md](references/ERROR_PATTERNS.md) からエラーパターンを特定
3. 解決策とコード修正を提供

## 参照

- [ERROR_PATTERNS.md](references/ERROR_PATTERNS.md) - エラーパターンデータベース

description内の自動検出,トリガーパターンセクションが適用のトリガーになります。ここに記述したパターンがターミナル出力に含まれると、Claude Code が自動的にこのスキルを適用します。

導入方法

ClaudeCodeでインストール

ClaudeCodeの入力欄で実行します（シェルではありません）。

/plugin marketplace add akaitigo/claude-skills-quarkus
/plugin install claude-skills-quarkus@claude-skills-quarkus

手動インストール

git clone https://github.com/akaitigo/claude-skills-quarkus.git
cp -r claude-skills-quarkus/skills/* ~/.claude/skills/

補足: 複数プロジェクトを同時に起動する場合

同じ端末で複数の Quarkus アプリを起動すると、ポートや Dev Services が衝突します。
今回は単に生成をSkillとして行うことだけを目的にしたため、複数サービスでも問題無く起動出来ることは対応していません。
必要に応じて application.properties に以下を追記します（例）。プロジェクトごとに値を変えてください。

quarkus.http.port=8081
%dev.quarkus.datasource.devservices.db-name=order-service-db

動作イメージ

┌─────────────────────────────────────────────────────────────┐
│ $ ./gradlew build                                           │
│                                                             │
│ > Task :compileKotlin FAILED                                │
│ e: Unresolved reference 'listAll'                           │
│ e: Unresolved reference 'findById'                          │
└─────────────────────────────────────────────────────────────┘
                            ↓
            Claude Code が検知してスキル適用
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ ## Error Summary                                            │
│ Kotlin Panache Entity に PanacheCompanion がありません      │
│                                                             │
│ ## Solution                                                 │
│ companion object : PanacheCompanion<Task> を追加            │
│                                                             │
│ ## Code Example                                             │
│ @Entity                                                     │
│ class Task : PanacheEntity() {                              │
│     companion object : PanacheCompanion<Task>  // 追加      │
│     lateinit var title: String                              │
│ }                                                           │
└─────────────────────────────────────────────────────────────┘

まとめ

今回作成したAgentSkillsはGitHubで公開しています。興味のある方は見られてみてください。

GitHub: https://github.com/akaitigo/claude-skills-quarkus

Skillを作成してみてですが、チームで同一のAgentSkilsを使うことで知見が勝手に共有され、タスクの手順が自動的に更新されていく状態を作ることが出来ますので生産性を上げるために効くと思えました。
今までのMCPが明確なツールとして利用できるが永続するためコンテキストを圧迫してしまう、Agents.mdが情報・ルールとして与えることは出来るが実行は明確に定義出来なかったと一長一短だった中、エージェントに渡す知識、ツールを必要な時だけ渡せるAgetnSkillsが出てきたのはありがたいですね。標準にもなっていきそうですし。
GeminiCLIでもロードマップには追加されているので、どのコーディングエージェントでも利用可能になり、ツールに縛らず利用可能な状態に早くなると良いなと思います。

ただ、Skillのテストが行いづらい、Skillを読みに行くトリガーがはっきりとしていない点には課題を感じました。
テストについては自身でエラーを埋め込んだプロジェクトを用意していてもSkillが追加されたセッションで手動でプロンプトを送る必要があるのは手間ですし、トリガーについてもdescriptionに長く書きすぎると結局コンテキストの圧迫に繋がってしいますのでどこまで書くと良いのかの塩梅が分からないというのがあります。
テストが行いやすくなる仕組みや、descriptionとは別でSkillの使い時を記入できる項目(triggerとか)があると良いなと思いました。

明日は@hiraishi_satoshiさんの「Quarkusで作る小売向け統計分析API」です。お楽しみに！

RetailAIとTRIALではエンジニアを募集しています。興味がある方はご連絡ください！

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up