adding-a-skill

スキルの追加

このリポジトリで公開スキルを作成するときに使用します。通常のスキル変更は skills/<skill-name>/ に配置し、リポジトリ内だけのガイダンスは .agents/skills/ に配置してください。

まずスキルの種類を決める

• 通常の公開スキル： SKILL.md を含む、skills/<name>/ 配下の通常のフォルダーです。一般的なケースです。@agent-native/skills は BuilderIO/skills@main からこれらを動的に検出するため、npx @agent-native/skills@latest add --skill <name> を機能させるだけなら、フレームワークのレジストリを編集する必要はありません。
• 指示スタイルのスキル： ユーザーが --update-instructions を指定したときに、常時適用される管理対象の AGENTS.md / CLAUDE.md の行を任意で書き込む、通常のスキルです。追加のフレームワーク変更が必要です。下記の「管理対象の指示ブロック」を参照してください。
• アプリ連携型 / MCP スキル： ホスト型またはローカルの MCP サーバーを登録する、あるいはフレームワーク管理のインストール動作を使用するスキルです。通常の公開スキルではありません。../agent-native/framework/packages/core/src/cli/skills.ts と ../agent-native/framework/packages/skills/src/built-in-apps.ts を確認してください。
• プランスキル： visual-plan と visual-recap には、このリポジトリと ../agent-native/framework の間で生成・同期されるコピーがあります。単独の説明文フォルダーとして扱わないでください。
• Rewind： 正規の SKILL.md は Agent Native から生成されます。これは、指示とローカルの Screen Memory ツールがプライバシーに関する共通の契約を共有しているためです。人が読む README はここに保持し、生成されるスキルは手作業で編集せず、npm run sync:agent-native-skills を使用してください。

通常の公開スキルのチェックリスト

1. skills/<skill-name>/SKILL.md を作成または更新します。

2. 公開カタログにスキルを掲載する場合は、skills/<skill-name>/README.md を追加します。このリポジトリでは、公開スキルページに README を使用します。

3. コレクションの位置付けを変更する場合は、ルートの README.md、.codex-plugin/plugin.json、.claude-plugin/plugin.json、および package.json の説明を更新します。

4. スキルは簡潔に保ちます。SKILL.md にはエージェントに必要な指示だけを記載し、スキルを直接支援しない追加ドキュメントは避けてください。

5. 次のコマンドで検証します。

   python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>
   

6. CLI 経由で動作すると説明する前に、ローカルでインストール検出をスモークテストします。

   node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json
   

7. npm run check を実行します。変更と無関係な visual-plan / visual-recap の同期エラーで失敗した場合は、それらのスキルを安易に書き換えず、その旨を具体的に報告してください。

@agent-native/skills のインストール経路

通常の公開スキルの場合、インストール経路は動的です。

• ../agent-native/framework/packages/skills/src/index.ts で DEFAULT_SKILLS_SOURCE = "BuilderIO/skills" が設定されています。

• このリポジトリを実体化し、resolveSkillsRoot を介してプラグインマニフェストを読み込み、discoverSkills を使ってすべての skills/*/SKILL.md を検出します。

• そのため、skills/<name>/ 配下に新しいフォルダーを追加するだけで、次のコマンドが使えます。

  npx @agent-native/skills@latest add --skill <name>
  

アプリ連携型のスキル、または独自のインストール動作が必要なスキルでない限り、@agent-native/core の組み込みレジストリを変更する必要はありません。

管理対象の指示ブロック

スキルによって --update-instructions 経由で AGENTS.md / CLAUDE.md に反映させる場合は、フレームワークのラッパーを更新します。

• ../agent-native/framework/packages/skills/src/index.ts の instructionContentForSkill(skillName) 内に簡潔な行を追加します。

• ../agent-native/framework/packages/skills/src/index.spec.ts のテストを追加または更新します。

• 次を実行します。

  pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
  

quick-recap、efficient-fable、stay-within-limits のような、長期的に適用する動作ルールや、read-the-damn-docs のような、まずドキュメントを確認する動作に使用します。

アプリ連携型または MCP スキル

ホスト型ツール、認証、MCP 登録、ローカルファイルモード、または特別なインストールフラグが必要なスキルの場合は、編集前にフレームワークを確認してください。

• ../agent-native/framework/packages/core/src/cli/skills.ts
• ../agent-native/framework/packages/skills/src/built-in-apps.ts
• ../agent-native/framework/packages/skills/src/sync-with-core.spec.ts

コアとスタンドアロン版 @agent-native/skills の MCP 記述子を同期してください。

Agent Native スキル同期時の注意点

visual-plan、visual-recap、および rewind は特殊です。

• Framework には、正規版／生成されたコピーと、Plan マーケットプレイス用バンドルが含まれています。
• このリポジトリの npm run check はそれらのコピーを比較するため、新しい通常のスキルとは無関係な差分が原因で失敗することがあります。
• Plan スキルを意図的に変更する場合は、生成されたコピーを手動で編集するのではなく、framework の同期パスを使用してください。framework 内で sync-plan-marketplace、sync-workspace-skills、および skills.sync.spec.ts を検索してください。
• Rewind の SKILL.md は packages/core/src/cli/skills-content/rewind-skill.ts から生成されます。公開 README はオーバーレイとして保持されます。通常のコピー用インストーラーでは Rewind のローカル MCP 接続を設定できません。公開セットアップドキュメントでは @agent-native/skills または @agent-native/core を使用してください。
• skills/ ディレクトリ全体を公開するプラグインマニフェストには、常時有効なセットアップ指示を含める必要があります。Clips がない状態で Rewind を呼び出した場合は、公式インストールフローを開く前に許可を求めてください。キャプチャを黙ってインストールまたは有効化してはならず、Core がローカル MCP 接続を設定して screen_memory_status が成功するまで、Rewind を利用できない状態にしてください。

最終報告

スキルの変更を完了したら、次の内容をユーザーに伝えてください。

• 変更したスキルファイル。
• @agent-native/skills による動的なインストール検出で十分かどうか。
• framework 管理の指示の変更を追加したか、意図的に後続作業として残したか。
• 成功または失敗した検証コマンド。Plan の同期とは無関係な失敗も含めてください。