| name | manage-agent-skills |
| description | dotfiles リポジトリの agent-resources で skill または agent definition を作成・更新・整理するときに使う。 `agent-resources/skills` と `agent-resources/agents` を source of truth とし、skill は `.agents/skills` と `.claude/skills`、agent definition は `.agents/agents`、`.claude/agents`、`.codex/agents` への公開 symlink と検証を維持する。 例: 「新しいスキルを作って」「対応するスキルを更新して」「agentを追加して」 |
| disable-model-invocation | true |
manage-agent-skills
dotfiles リポジトリで agent skill と agent definition を作成・更新する。
Scope
- Skill:
agent-resources/skills/<skill-name>/SKILL.md（付随 resource: references/, scripts/, assets/, agents/openai.yaml）
- Agent definition:
agent-resources/agents/<agent-name>/<agent-name>.md（canonical）と codex.toml
- 公開 skill symlink:
.agents/skills, .claude/skills
- 公開 agent symlink:
.agents/agents, .claude/agents, .codex/agents
<skill-name> / <agent-name> には小文字英数字とハイフンだけを使う。
Resources
references/repository-links.md: 公開 symlink を作成・検証する前に読む。scripts/maintain-skill.sh <skill-name>: skill の symlink 作成と検証に使う。scripts/maintain-agent-definition.sh <agent-name>: agent definition の symlink 作成に使う。
Hard constraints
- Markdown 構造・YAML frontmatter・見出し・リスト・表・fenced code block・コードブロック内の改行を保持する。
- 通常の段落は概ね1文1行、リスト項目は1項目1行にする。
- 直接的な命令形・肯定形の指示・正確な相対パス・「X ならば Y。そうでなければ Z。」の条件文を使う。
- 否定形の表現は、ハード禁止・安全境界・データ損失リスク・フォーマット崩壊リスク・交渉不可の制約にだけ使う。
SKILL.md は運用的な内容に保ち、長い例・スキーマ・対応表・コマンド規約・背景・詳細ルールは reference file に移す。- 各規約の正典となる置き場所は1つだけにし、単発利用の抽象化・投機的な柔軟性・不要な resource ディレクトリを避ける。
- shell script は
scripts/*.sh としてだけ追加する。
- shell や validator の出力は、コマンド・pass/fail・必要なエラー行だけを報告する。
Workflow
Step 1: Confirm scope
依頼が曖昧な場合は、編集前に短く確認する。
既存内容を更新する場合は、まず現在の構成とスタイルを読む。
skill を更新する場合は、関連する SKILL.md セクション・reference・script・asset を探し、canonical な置き場所を決めてから編集する。
Step 2: Create or update skill
新しい skill を作る場合は skill-creator initializer を使う。
SKILL.md の frontmatter は name と description だけにする。
skill が何をするか・いつ使うかは description に書く。
実行時の workflow・制約・resource の使い方は本文に書く。
反復的で決定論的な作業は scripts/ に切り出して実行する。
resource が必要なら skill 配下に作り、SKILL.md から正確な相対パスで参照する。
詳細が SKILL.md と reference file の両方に該当する場合、詳細は reference file に置き、SKILL.md には読むタイミングと短い指示だけを残す。
Step 3: Create or update agent definition
<agent-name>.md: 単一の canonical contract。YAML frontmatter（name, description, model, tools などの Claude Code サブエージェント項目）を含め、canonical source と Claude Code サブエージェント定義を1ファイルで兼ねる。codex.toml: Codex 用メタデータ（name, description, model, sandbox_mode など）と、.agents/agents/<agent-name>.md（canonical への symlink）を読んで primary contract として従わせる短い developer_instructions bootstrap。Codex の config schema には per-agent の instructions ファイル参照キーが無いため、契約全文を developer_instructions に複製しない。
Step 4: Link and validate
touched skill には次を実行する:
agent-resources/skills/manage-agent-skills/scripts/maintain-skill.sh <skill-name>
touched agent definition には次を実行する:
agent-resources/skills/manage-agent-skills/scripts/maintain-agent-definition.sh <agent-name>
既存の公開パスが期待する symlink でない場合は、置き換える前に停止して確認する。
validation が touched-file の issue を報告したら、直して再実行する。
agent definition 専用の validator は無いため、maintain-agent-definition.sh を実行し、リンク先ファイルを読んでから終える。
validation を実行できない場合は、理由と手動で確認した内容を報告する。
終える前に diff を見直し、概念の重複・コピーされた例・path / command 規約の繰り返しを確認する。
standalone 実行のための意図的な重複を残す場合は、その理由を報告する。
Report
変更した skill path、変更した agent definition path、作成・確認した symlink path、script のコマンドと結果、validator のコマンドと結果、validation を省略した理由、意図的な重複とその理由を報告する。
