igapyon/igapyon-agent-skills

# GitHub Repository: igapyon/igapyon-agent-skills

**URL:** https://github.com/igapyon/igapyon-agent-skills
**Author:** igapyon
**Description:**   A personal repository for managing Agent Skills used for Japanese Note/Qiita   article writing, companion-style technical and music post writing, GitHub text   drafting, and Mikuku character-agent workflows.
**Homepage:** 
**Language:** JavaScript

## Stats
- Stars: 0
- Forks: 0
- Open Issues: 7
- Commits: 367
- Created: 2026-03-10T23:47:43Z
- Updated: 2026-06-22T00:58:18Z
- Pushed: 2026-06-22T00:59:04Z

## README
# igapyon-agent-skills

個人用の Agent Skills を管理するためのリポジトリです。

日本語の Note / Qiita 記事作成と、技術・音楽投稿の伴走型ライティング支援に使う skill を置いています。

## 方針

- skill は `skills/` 配下に置く
- 1 skill = 1 directory
- skill ごとの詳細仕様は各 `SKILL.md` に書く
- skill の具体ルール、例、長めの手順は `references/` 配下に置く
- Note 記事 Markdown は、姉妹リポジトリ `../mikuku-articles/` を正本として管理する
- Qiita 記事 Markdown は、`skills/igapyon-qiita-writer/references/` を正本として管理する
- skill を新規作成・更新した後は、`SKILL.md` が必要な `references/` を案内していること、必要に応じて `index.json` を参照することを確認する
- repo 全体の運用ルールはこの `README.md` に書く
- 作業メモは repo 直下の `TODO.md` に集約する
- skill ごとの `index.json` は `miku-indexgen` で生成する
- ローカル作業用に `workplace/` を置き、`workplace/.gitkeep` だけを Git 管理下に入れる
- Java / Maven 開発では `.mvn/jvm.config` を repo に含める

## バージョン更新

この repo 全体のバージョンは、root の `pom.xml` を正本として管理します。

バージョン形式は `1.YYYYMMDD.N` を基本とし、`YYYYMMDD` はその保守更新日、`N` は同じ日付内の更新番号を表します。  
たとえば 2026-05-21 の最初の保守更新では、repo 全体のバージョンを `1.20260521.1` にします。

repo 全体のバージョンを更新するときは、日付部分に合わせて `skills/igapyon-mikuku-agent/references/VERSION.md` の `Version` も更新します。  
`みくく` のバージョンは `YYYYMMDDx` 形式で、`YYYYMMDD` を repo 全体のバージョンの日付部分と揃えます。  
同じ日付内の更新は、`みくく` 側では `a`, `b`, `c` ... と suffix を進め、repo 全体のバージョンでは対応する `N` を `1`, `2`, `3` ... と進めます。

バージョン更新時は、次の両方を確認します。

- root の `pom.xml`
  - 例: `<version>1.20260604.1</version>`
- `skills/igapyon-mikuku-agent/references/VERSION.md`
  - 例: `Version: 20260604a`
- `mvn clean package` で生成される release archive 名
  - 例: `target/igapyon-agent-skills-1.20260604.1.zip`

`みくく` 側だけを更新したい場合でも、repo 全体の保守更新として扱うなら `pom.xml` も同じ日付に更新します。逆に、repo 全体のリリースや保守更新ではない一時的な確認だけなら、バージョンを更新しません。

`mvn generate-resources` や `mvn clean package` では、`pom.xml` の `1.YYYYMMDD.N` と `skills/igapyon-mikuku-agent/references/VERSION.md` の `YYYYMMDDx` が対応していることを `validate` phase で確認します。たとえば `1.20260604.1` には `20260604a`、`1.20260604.2` には `20260604b` を対応させます。

## 記事公開の優先順位

技術記事は、まず Note 向けの記事として作成・公開することを優先します。

Note では、みくく担当のテック主記事を一次公開記事として扱います。  
文体は Qiita 寄りの技術記事文体とし、技術内容、使い方、CLI、仕様、手順、コマンド例などをしっかり含めます。

Qiita では、Note のテック主記事をもとに、技術詳細、手順、CLI リファレンス、設定例、コマンド例などをより参照しやすい形で後追い整理します。

従来型の Note 記事も引き続き作成します。  
こちらはうさぴょん担当とし、Note らしい柔らかい文体で、開発背景、使いどころ、利用イメージ、つまずきや意図などを含めた読み物として整えます。

記事の正本管理は、媒体ごとに分けます。

- Note 向け記事の正本: `../mikuku-articles/`
  - 公開済み記事: `../mikuku-articles/2026/<MM>/<YYYYMMDD>/`
  - 未公開記事: `../mikuku-articles/2026/draft/`
- Qiita 技術記事の正本: `skills/igapyon-qiita-writer/references/`

Qiita 側は投稿頻度や下書き作成数に制限がかかる場合があるため、公開は間隔を空けて行います。  
Note 記事の下書きや移行中の記事は、`../mikuku-articles/2026/draft/` に平置きで保持し、公開日が決まった段階で日付ディレクトリへ移します。

## 移行期の writer skill 運用

Note 優先運用への移行期は、掲載媒体ではなく記事タイプで writer skill を選びます。

みくく担当の Note テック主記事は、Note 掲載であっても `igapyon-qiita-writer` を使って作成・整理します。  
これは、文体と情報密度を Qiita 寄りの技術記事として保つためです。

うさぴょん担当の従来型 Note 記事は、`igapyon-note-writer` を使って作成・整理します。  
こちらは、技術詳細を詰め込みすぎず、背景、感触、読み物としての流れを優先します。

記事ファイルの正本配置は、利用した writer skill ではなく掲載媒体に合わせます。  
そのため、`igapyon-qiita-writer` で作成した Note テック主記事でも、Note 掲載用の正本は `../mikuku-articles/` に置きます。

## .gitignore の扱い

macOS が生成する `.DS_Store` は Git 管理対象外とするため、repo 側の `.gitignore` に記載します。

`workplace/` は clone した外部リポジトリ、展開した zip、生成物、検証用ファイルなどを置くローカル作業フォルダです。  
`workplace/` 配下の作業物は Git 管理対象外とし、ディレクトリを維持するための `workplace/.gitkeep` だけを Git 管理下に入れます。

`.codex/skills/` は Codex から利用するためのローカル配備先です。  
この repo では `skills/` 配下を正本として管理し、`.codex/skills/` 配下のコピーは Git 管理対象外とします。
`skills/` から `.codex/skills/` への反映は、必要なタイミングで手動実行します。Maven の `package` フェーズでは自動コピーしません。

## Codex skills 更新後の反映 tips

Codex skills を更新した後、基本は VS Code のウィンドウ再読み込みで有効になります。

コマンドパレットから実行する場合は、次を実行します。

```text
Developer: Reload Window
```

macOS の通常操作では、次のショートカットでコマンドパレットを開きます。

```text
Cmd+Shift+P
```

その後、`Reload Window` を実行します。

ターミナルから VS Code を操作できる環境では、対象ワークスペースで次のコマンドでも近い動きになります。

```sh
code -r .
```

ただし、`code -r .` は同じウィンドウを再利用して開き直す動きです。拡張や Codex 側の状態更新まで確実に反映したい場合は、VS Code 内の `Developer: Reload Window` を使うのが一番確実です。

## Java / Maven の扱い

Java / Maven を使う repo では、実行時の JVM 設定を repo 側で明示するため、`.mvn/jvm.config` を Git 管理下に入れます。

この repo では、ローカル環境での名前解決やネットワーク挙動を安定させるため、IPv4 を優先する JVM オプションを `.mvn/jvm.config` に記載しています。

## references の扱い

各 skill 配下の `references/` は、skill 利用時に参照しやすいように同梱する参考資料です。

skill を利用する際は、`SKILL.md` を入口とし、具体ルール、例、長めの手順、参照記事、テンプレートなどは必要に応じて各 skill 配下の `references/` を読んで適用します。  
`SKILL.md` には発火条件、基本フロー、参照先の案内を中心に置き、詳細は `references/` 側を利用する方針です。

`skill-creator` などで skill を作成した直後は、必要な具体ルールを `SKILL.md` に詰め込みすぎず、`references/` へ分離します。  
また、参照資料の全体像を探す必要がある skill では、`SKILL.md` に `index.json` を discovery index として使う旨を明記します。

Note / Qiita 記事 Markdown は、媒体ごとの正本置き場で管理します。

- Note 記事の正本: `../mikuku-articles/`
- Qiita 技術記事の正本: `skills/igapyon-qiita-writer/references/`

みくく担当の Note テック主記事は、正本を `../mikuku-articles/` に置きます。  
一方で、みくく文体の参照例として使うため、公開済みまたは参照価値の高い記事コピーを `skills/igapyon-mikuku-agent/references/examples/articles/` に同期して置きます。

このコピーは文体・構成の参照用です。記事本文、URL、掲載用属性を更新する場合は、まず Note 正本側を更新し、その後で `igapyon-mikuku-agent` 側の writing example にコピーして同期します。

`../mikuku-articles/2026/draft/` は、日付未確定または未公開の Note 記事を階層なしで置く場所です。  
公開済み Note 記事は、`../mikuku-articles/2026/<MM>/<YYYYMMDD>/` 配下の記事パッケージとして管理します。

`workplace/*/docs/articles/` やこの repo の旧配置に記事メモや Markdown が残っている場合でも、Note 記事として更新・公開対象にする正本は `../mikuku-articles/` 側です。

## docs/articles 集約状況

記事管理は現在、Qiita 向け記事を `skills/igapyon-qiita-writer/references/`、Note 向け記事を `../mikuku-articles/` に集約し、そこを正本として扱う方針です。

2026-05-06 時点で、`workplace/*/docs/articles/qiita/` 配下の有意な記事本文は、`README.md` と `TEMPLATE.md` を除き、すべて `skills/igapyon-qiita-writer/references/` 側に同一内容で存在することを確認済みです。

対象は次の通りです。

- `miku-abc-player`: 1 件
- `miku-indexgen`: 1 件
- `miku-xlsx2md`: 8 件
- `mikuproject`: 4 件
- `mikuscore`: 2 件

同じく 2026-05-06 時点で、`workplace/*/docs/articles/note/` 配下の有意な記事本文は、`README.md` と `TEMPLATE.md` を除き、いったん `skills/igapyon-note-writer/references/` 側に同一内容で集約済みであることを確認しました。現在は、公開済み記事を含む Note 正本を `../mikuku-articles/` 側へ移しています。

対象は次の通りです。

- `miku-abc-player`: 1 件
- `miku-indexgen`: 1 件
- `miku-xlsx2md`: 3 件
- `mikuproject`: 3 件
- `mikuscore`: 2 件

`mikuscore` の記事は、`workplace/docs-articles/mikuscore-devel/` と `workplace/docs-articles/miku-abc-player-devel/vendor/mikuscore/` の両方に重複して存在する場合があります。  
Note 正本側では、`../mikuku-articles/` に 1 セットとして保持します。

一般記事の Note 下書きは、`../mikuku-articles/2026/draft/` に置きます。

## 構成

```text
.
├─ skills/
│  ├─ igapyon-qiita-writer/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-note-writer/
│  │  ├─ SKILL.md
│  │  └─ templates/
│  ├─ igapyon-companion-techpost-writer/
│  │  └─ SKILL.md
│  ├─ igapyon-companion-musicpost-writer/
│  │  └─ SKILL.md
│  ├─ igapyon-github-writer/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-diary-writer/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-ffmpeg-helper/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-agent-state-management/
│  │  ├─ SKILL.md
│  │  ├─ references/
│  │  └─ templates/
│  ├─ igapyon-miku-soft-developer/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-mikuku-agent/
│  │  ├─ SKILL.md
│  │  ├─ assets/
│  │  └─ references/
│  ├─ igapyon-repo-conventions/
│  │  ├─ SKILL.md
│  │  └─ references/
│  ├─ igapyon-reviewer/
│  │  ├─ SKILL.md
│  │  └─ references/
│  └─ igapyon-skill-compactor/
│     ├─ SKILL.md
│     └─ references/
├─ pom.xml
├─ TODO.md
└─ README.md
```

## 現在の skill

- `igapyon-qiita-writer`

  Qiita 向けの日本語技術記事の作成、整理、改善向け。明示的に指定した場合、または Qiita 記事化の意図が明確な場合に利用する。

- `igapyon-note-writer`

  Note 向けの日本語記事の作成、整理、改善向け。明示的に指定した場合、または Note 記事化の意図が明確な場合に利用する。

- `igapyon-companion-techpost-writer`

  技術系日本語投稿の伴走、最小整理、全文再構成向け。明示的に指定した場合、または伴走型の最小整理が明確に求められた場合に利用する。

- `igapyon-companion-musicpost-writer`

  音楽系日本語投稿の伴走、最小整理、全文再構成向け。明示的に指定した場合、または伴走型の最小整理が明確に求められた場合に利用する。

- `igapyon-github-writer`

  GitHub PR、GitHub Release、GitHub About に貼る文章の作成向け。明示的に指定した場合に利用する。

- `igapyon-diary-writer`

  igapyon diary repository の日記エントリ作成・更新向け。明示的に指定した場合、または diary repository の作業が明確な場合に利用する。

- `igapyon-ffmpeg-helper`

  H4essential のオーケストラ録音から、切り出し、単純ゲイン調整、必要なら結合、静止画付き YouTube 用動画作成までの個人用 FFmpeg ワークフロー向け。明示的に指定した場合に利用する。

- `igapyon-agent-state-management`

  AI エージェント作業用の `GOAL.md`、`TODO.md`、`DECISIONS.md` による軽量な状態管理ファイルの作成・整理・運用向け。発火は `igapyon-agent-state-management` の明示、または `igapyon 状態管理`、`igapyon 作業状態`、`igapyon 作業再開`、`igapyon 3ファイル`、`igapyon goal`、`igapyon todo` などの `igapyon` 付き合言葉を基本とする。`igapyon 作業再開` では、3ファイルを新規作成せず、まず既存の repo 状態、`TODO.md`、`GOAL.md`、`DECISIONS.md` などを読んで再開ポイントを整理する。

  名前を思い出せない場合は、`igapyon 状態管理` または `igapyon 作業再開` を合言葉として使う。

- `igapyon-miku-soft-developer`

  miku-soft project の新規作成・既存保守ワークフロー向け。skill の利用を明示的に指定した場合のみ利用し、miku-soft 作成・保守の相談だけでは存在案内に留める。

- `igapyon-mikuku-agent`

  日本語キャラクター agent `みくく` として応答するための会話スタイル向け。明示的に指定した場合に利用する。

- `igapyon-repo-conventions`

  Git / GitHub repository の `.gitignore`、`workplace/`、`.codex/skills/`、Java / Maven 設定、README 運用ルールの整理向け。明示的に指定した場合に利用する。

- `igapyon-reviewer`

  コード、記事、ドキュメント、UI 文言、CLI 文言などのレビュー向け。明示的に `igapyon-reviewer` の利用を指定した場合に利用する。

- `igapyon-skill-compactor`

  肥大化した Agent Skill の token-efficiency 設計、分割、参照化、蒸留、チェックリスト化、tool 化判断向け。明示的に指定した場合、または Agent Skill の compact / slim / token bloat reduction が明確な場合に利用する。

## index.json の更新

各 skill の `index.json` を更新する場合は、次のコマンドで `skills/` 配下をまとめて再生成します。

```sh
mvn generate-resources
```

ビルド全体とあわせて更新する場合は、次のコマンドでも `index.json` を更新できます。

```sh
mvn clean package
```

生成された `index.json` は、skill と一緒にコミットします。

## Release archive

GitHub Release に添付する利用者向け archive は、次のコマンドで作成します。

```sh
mvn clean package
```

生成物は `target/igapyon-agent-skills-<version>.zip` です。

archive には `README.md`、`INSTALL.md`、`LICENSE`、`pom.xml`、`.mvn/`、`lib/`、`skills/` を含めます。
利用者は archive を展開し、`INSTALL.md` の手順で `skills/*` を自分の Codex skills directory へコピーします。

release archive には、この repo の `skills/` に加えて、外部管理の miku-soft 系 skill も同梱します。
外部 skill は `mvn package` の `prepare-package` フェーズで `target/release-staging/skills/` に取得し、archive 化します。
取得元は `pom.xml` の `external.*` properties で固定します。

同梱する外部 skill は次の通りです。

- `miku-indexgen-skills` `v1.6.1`: `skills/igapyon-miku-indexgen/`
- `miku-text-bundle-skills` `v1.1.1.2`: `skills/igapyon-miku-text-bundle/`
- `miku-repo-bundle-skills` `v0.5.0.1` (experimental): `skills/igapyon-miku-repo-bundle/`
- `miku-grep-skills` `v0.10.1.1` (experimental): `skills/igapyon-miku-grep/`
- `miku-prompt-lint-skills` `v0.4.1`: `skills/igapyon-miku-prompt-lint/`
- `miku-readfile-skills` `v0.5.0.2`: `skills/miku-readfile/`
- `mikuproject-skills` `v0.8.1.1`: `skills/mikuproject/`
- `mikuscore-skills` `v0.1.0`: `skills/mikuscore/`

GitHub では `v*` tag が push されたときに GitHub Actions で `mvn clean package` を実行し、生成された zip を GitHub Release asset として添付します。