EdwardAstill/agentfiles

Mission（エージェント向け）

このリポジトリは成長指向のエージェントハーネスです。すべてのタスクはシステム自体を改善する機会です。しかし、本当に目的に役立ち、それを実現する最善の方法である場合にのみ、何かを追加してください。肥大化は第一級の失敗です。既存のコマンドをラップしただけのもの、他のドキュメントを言い換えただけのもの、呼び出し側が1つしかないCLIなどです。新しいものを追加する前に、自問してください。この機能はすでに存在するか？単純なrg / cat / touchで十分か？もしそうなら、追加しないでください。

覚えておく価値のあることを発見した場合は、af noteで追記するか、直接research/lessons/にファイルを作成してください。研究スキルはシステムが自己学習できるように存在します。推測に頼る前にそれらを使用してください。

アーキテクチャ変更を計画する前に、エージェントナレッジを参照してください

research/knowledge/はプロジェクトの長期記憶です。research/内のすべて（論文、プロジェクト、ドキュメント、教訓）を蒸留した出力です。ハーネス、オーケストレーション、またはスキルシステムの変更を提案する前に、すでに研究された内容を確認してください。

af ak list                           # research/knowledge/ ページの一覧表示
af ak show <slug>                    # 1ページを読む
af ak grep "<pattern>"               # knowledge/ 内の全文検索
rg "<pattern>" research/             # researchツリー全体を検索（生の入力も含む）
af archetype match "<user intent>"   # このタスクは既知の形状と一致するか？

ナレッジページがすでにその範囲をカバーしている場合は、再発見するのではなく、その上に構築してください。教訓があなたのやろうとしていることと矛盾する場合は、立ち止まって調整してください。

毎週の改善ループ

自己改善メカニズムは、誰かが実行して初めて効果を発揮します。af log review + af skill-usage summaryを毎週（cronまたはカレンダーリマインダー）スケジュールし、その出力に基づいて行動してください。

# ~/.config/systemd/user/... または crontab -e
0 9 * * 0  /home/you/.local/bin/af log review >> ~/.claude/logs/reviews/$(date +\%F).md

レビュー後、以下をざっと確認してください。

• ~/.claude/logs/observations.md — af log reviewによって草稿された異常と教訓。繰り返し発生するパターンをスキル編集またはナレッジページに昇格させます（research/knowledge/README.mdの昇格ルールを参照）。
• af skill-usage summary — 「一度もロードされていない」リストはカタログ内のデッドウェイトを示します。「トップディスパッチチェーン」は候補となるトリガーワイヤリングを示唆します。

2週連続で行動に値するものが何も生まれなかった場合、それもまたシグナルです。「何もしなかったレビュー」をresearch/lessons/に記録して、儀式に過剰適合するのを避けてください。

---

agentfiles — Claude Codeガイダンス

このリポジトリは、個人用Claude Codeスキルスイートの信頼できる情報源です。スキルは、af installを介して~/.claude/skills/（ユーザーレベル）または.claude/skills/（プロジェクトレベル）にシンボリックリンクされます。

スラッシュコマンド

スキルは/skill-nameの形式（例：/git-expert、/brainstorming）を使用します。これらは手動オーバーライドです。何をしたいか正確にわかっている場合に使用してください。そうでなければ、executorが自動的にルーティングを処理します。

日常的な使用ではこれらを入力する必要はありません。using-agentfilesがセッション開始時に起動し、システムが自動的にexecutorを介してルーティングします。

どのスキルをいつ使うか

状況	スキル
新しいタスク（デフォルト）	executor
新機能 / コンポーネント / デザイン	最初にbrainstorming、次にexecutor
バグまたは予期しない動作	systematic-debugging
コードベースに不慣れ	codebase-explainer
実行する実装計画	writing-plans → subagent-driven-development
Python / TypeScript / Rust / Typst	python-expert / typescript-expert / rust-expert / typst-expert
API設計またはレビュー	api-architect
データベーススキーマ / マイグレーション / クエリ	database-expert
セキュリティ監査	security-review
パフォーマンス問題	performance-profiling
大規模な再構築	refactoring-patterns
Docker / K8s / Terraform	infrastructure-expert
依存関係の更新 / CVEスキャン	dependency-management
ロギング / トレーシング / メトリクス	observability
Webアクセシビリティ	accessibility
Git操作 / ワークツリー	git-expert / git-worktree-workflow
GitHub PR、Issue、Actions	github-expert / github-actions-expert
「Xの使い方は？」— APIルックアップ	docs-agent
「Xを使うべきか？」— トレードオフ	research-agent
参考資料からの質問に答える	test-taker
ノートやインタラクティブレッスンを書く	readrun
並列マルチエージェントワーク	manager
スキルの作成または編集	writing-skills

重要な事実

• スキルは agentfiles/<category>/.../<skill-name>/SKILL.md に配置 — management/、planning/、coding/、research/ の4つのカテゴリ
• 各カテゴリにはディスパッチャー が agentfiles/<category>/SKILL.md にあり、正しいリーフスキルにルーティング
• af agents --tree を実行 して完全なライブ階層を表示
• 地域別ドキュメント は agentfiles/<category>/REGION.md にあり、managerは計画中にこれらを読み込み
• インストール: ./install.sh（ブートストラップ）、その後 af install（フルインストール）。新しいマシンには ./bootstrap.sh を使用
• CLI: af <subcommand> — tools/python/src/af/ にあるPython CLI、uv tool でインストール

スキルファイル形式

---
name: skill-name          # 小文字、ハイフンのみ
description: >
  トリガー条件の場合に使用。合計1024文字未満に保つ。
  これはClaudeがスキルを呼び出すかどうかを判断するために読み取る内容です。
---

descriptionフィールドは、このスキルを呼び出さずに他のスキルから見える唯一のものです。いつトリガーするかが明確になるように記述してください。

地域別ドキュメント同期ルール

新しいリーフスキルが追加または削除されるたびに、そのカテゴリのREGION.mdを更新してください。

地域別ドキュメント（agentfiles/<category>/REGION.md）は、managerが計画中に読み取るスキルカタログです。各エントリは### skill-nameの見出し形式を使用します。これらが現実から逸脱すると、managerは誤った計画を立てます。

agentfiles/への変更をコミットする前にaf checkを実行して、すべてのリーフスキルがそのカテゴリのREGION.mdにエントリを持っていることを確認してください。

manifest.toml

スキルごとのツール要件と、インストールするbinエントリを宣言します。以下の場合に更新してください。

• ツール要件を持つ新しいスキルを追加する場合
• 新しいbinエントリを追加する場合
• スキルのツール要件を変更する場合

[skills.skill-name]
tools = ["Bash", "Read"]   # Claude Codeツール名
mcp = ["context7"]         # MCPサーバー名（オプション）

新しいスキル追加 — チェックリスト

• カテゴリを決定: management/、planning/、coding/、または research/
• agentfiles/<category>/[sub-category/]<skill-name>/SKILL.md を有効なフロントマターで作成
• スキルがヘルパースクリプトを必要とする場合は scripts/ フォルダを追加
• manifest.toml の [skills.<skill-name>] にエントリを追加
• カテゴリの agentfiles/<category>/REGION.md に ### skill-name でエントリを追加
• af install を実行（シンボリックリンクは次回セッションで有効）

アーキテクチャノート

2パスオーケストレーション:

• executor — すべての新しいタスクのデフォルトエントリポイント。af context/af statusで方向付けを行い、その場でルーティングを決定し、タスクをエンドツーエンドで処理します。専門スキルはSkillツールを介してインラインで吸収します。完了報告前の検証は必須です。並列作業が本当に必要な場合にのみ、構造化されたHANDOFF CONTEXTブロックを使用してmanagerにエスカレーションします。
• manager — 真のマルチエージェントワーク専用。executorからハンドオフコンテキストを読み取り、計画レビューパス（設計？git戦略？調整？）を実行し、エージェントをディスパッチし、エージェントが失敗した場合は適応的再計画で結果をレビューします。アドバイザー（design-advisor、git-advisor、coordination-advisor）は、関連する決定が自明でない場合にのみインラインでロードされます。

スペシャリストはスキルライブラリであり、ルーティング先ではありません。 これらはexecutorによってSkill("name")でインラインロードされます。managerが明示的に並列ドメインワークを必要とする場合にのみ、サブエージェントとしてディスパッチされます。

GitエキスパートはWORKTREE CONTEXTブロックを出力します — 他のスキルは、変更を加える場所を知る必要がある場合にこれを探す必要があります。

スキルは独立しています — 各スキルは単独で動作します。オーケストレーターはその上にコーディネーションを追加するだけで、スタンドアロンの使用を置き換えるものではありません。

インストール

2段階インストール:

1. ブートストラップ (./install.sh): af CLIとagentfiles-managerスキルをグローバルにインストールします。最小限 — スキル選択もCLIツールもありません。
2. フルインストール (af install): すべてのスキル、フック、CLIツールをインストールします。--global（デフォルト）、--local、--skill、--category、--remove、--dry-runをサポートします。

2つのモード:

• モードA — すべてグローバル: ./install.sh && af install ですべてのスキルをグローバルにインストールします。プロジェクトごとの設定なしですべてのプロジェクトで動作します。
• モードB — マネージャーのみ: ./install.sh でマネージャーのみをインストールします。その後、各プロジェクトで「このプロジェクトをセットアップして」と言うと、agentfiles-managerが関連するスキルを選択してローカルの.claude/skills/にインストールします。

シンボリックリンクを使用し、コピーは使用しません。スキルファイルへの変更は即座に反映されます — 再インストールは不要です。

マニフェストTOMLパーサーはシンプルなawk/grepパイプラインです。manifest.tomlをクリーンに保ち、通常でない書式（値行のインラインコメント、複数行配列など）は避けてください。