agent-skills-catalog

Agent Skills カタログ：同期されたスキルファイル、ページ、評価結果

スキルカタログとは、別の場所にあるファイルについて説明するページの集まりです。そのため、ページには、あるコミット時点でスキルのリポジトリに記載されている内容だけを正確に記述し、それ以外は一切含めてはいけません。 このモジュールをリリースしたエンジニアが作成し、検証済みの特性として保証しています。同期処理は、あるコミット時点のスキルの全ファイルを読み込み、全体を一括で置き換えます。ビルドはディスクを読み込み、ネットワークには接続しません。すべての評価ファイルはレンダリングされるか、理由とともにテストを失敗させます。評価カードには、エージェントとプロンプトごとに最新の実行結果が表示されます。記録は references/provenance.md にあります。

使用する場面

リポジトリとして公開されている Agent Skills（それぞれに SKILL.md、README.md、CHANGELOG.md、evals/ フォルダーが含まれます）と、そのルール、リリース、インストールコマンド、エージェントの評価結果を一覧表示する Next.js App Router サイトのページを作成または拡張する場合。

使用しない場面

• スキル自体の作成や強化：それはスキル自身のリポジトリで行います。評価実行の結果をもとに修正する場合は、兄弟スキルである skill-eval-loop を使用します。
• エージェントの評価実行：実行は別の場所で行い、各スキルの evals/ にコミットします。このモジュールはそれを読み取るだけです。
• リポジトリ内の Markdown からブログやヘルプセンターを作成する場合：兄弟スキルの blog-markdown と help-center-markdown を使用します。ここで扱う Markdown は他者が作成したもので、編集することはありません。
• アカウント、アップロード、ダウンロードを扱うパッケージレジストリやマーケットプレイス：信頼モデルが異なります。

アーキテクチャ

skill repositories (GitHub, or local checkouts)
        |  npm run skills:sync   head sha first, every file at that sha, staged, swapped in whole
        v
content/skills/<slug>/meta.md          host-written: category, tagline, related
content/skills/<slug>/upstream/        sync-written only: SKILL.md README.md CHANGELOG.md
                                       references/provenance.md evals/*.md sync.json
content/skills/_index/README.md        optional index table: Builds and Backend cells
        |  build time, no network
        v
lib/skills/catalog.ts   getSkill(slug), getAllSkills(), categories, related     React cache()
  markdown.ts + upstream.ts   sections, rules, tables, releases, provenance (SKILL_LAYOUT)
  evals.ts                    prompts, parseEval (ok or reason), sortRuns, latestRuns
  validate.ts                 every problem the loader forgives, as errors and warnings
        |
        +-- /skills                 catalog: SkillSummary[] to a client search and filter
        +-- /skills/[slug]          a skill page, or a category page when the slug is a category
        +-- sitemap, JSON-LD        dates from the changelog, never from the build
        +-- catalog.test.ts         validateCatalog() errors fail npm test

重要な事実

1. 各スキルは2つの部分で構成されます。 meta.md にはリポジトリに含まれない情報（カテゴリー、タグライン、関連項目）が記載され、ホストだけが書き込みます。upstream/ にはリポジトリのファイルが置かれ、同期処理だけが書き込みます。
2. ディレクトリ構成はパーサーの契約です。 SKILL_LAYOUT はローダーが読み込む見出しを指定します。そこから逸脱したスキルでは該当セクションが失われ、バリデーターがその箇所を示します。文章から内容を推測することはありません。
3. 上流へのリンクは、そのリポジトリを基準とした相対パスです。 references/x.md はサイト上には存在しないため、SkillMarkdown はすべての相対リンクを GitHub 上の該当ファイルのフォルダーを基準に解決します。
4. [slug] の1つのセグメントでスキルとカテゴリーの両方を扱います。 dynamicParams = false によってすべてのページが静的になり、スキルのスラッグがカテゴリー ID と一致する場合はバリデーターが失敗します。
5. 実行ファイルは誰でも提案できる自由形式のテキストです。 組織自身のリポジトリにある Actions 実行 URL だけが「エージェントログ」リンクになります。JSON-LD では < がエスケープされます。
6. 実行ファイルはテキスト順ではソートされません。 -p1.md は -p1-2.md より後に並ぶため、日付、次に runNumber、最後に名前の順で並べます。
7. ビルドに GitHub は必要ありません。 ネットワークを使わない無人実行でも、assets/content/ にあるサンプルスキルをコミットすることで、ページ、バリデーター、テストにコンテンツを含められます。その後、npm run skills:sync に引き継ぎます。gray-matter、react-markdown、remark-gfm、vitest は npm から取得するもので、外部サービスではありません。テンプレートは書き換えずにコピーします。変更するのは adaptation.md に記載された接続部分の値だけで、5つのテストファイルは変更せずに実行されます：テストは24件です。

厳守事項

README と adaptation.md にある、同じ8項目を同じ順序で示します。

ビルド時やリクエスト時にスキルを取得しないでください。 同期ではリポジトリにファイルを書き込み、ビルドではディスクから読み取るため、デプロイが GitHub のレート制限やキャッシュに依存することはありません。

スキルのすべてのファイルを同じコミットから読み取ってください。 まず head sha を解決し、その sha で各ファイルを取得してください。ブランチ名を使った raw URL は数分間キャッシュされ、異なる2つのコミットが混在します。

スキルのミラーを丸ごと置き換えるか、まったく置き換えないでください。 フォルダーをステージングしてから所定の場所にリネームしてください。そうすれば、同期に失敗しても以前のコピーが残り、上流で削除されたファイルはここでも削除されます。

評価ファイルを黙って除外しないでください。 parseEval はファイルを表示できない理由を返し、validateCatalog() はそれぞれをエラーに変換して npm test を失敗させます。

エージェントとプロンプトごとに、最新の実行結果として記録されたものを表示してください。 失敗した実行も成功した実行と同じように表示され、再計算したり、見栄えのよい結果を選んだりすることはありません。実行履歴のないエージェントも名前を表示します。

frontmatter をテキストとして読み取る前に、YAML の日付を正規化してください。 引用符で囲まれていない date: 2026-09-26 は Date になり、Date をテキストとして読み取ると空文字列になって実行が拒否されます。

サイト上でスキルのテキストを再入力しないでください。 ルール、リリース、プロンプト、結果は upstream/ から取得します。meta.md に記載するのはリポジトリにない情報のみで、同期によって変更されることはありません。

クライアントに渡すのは概要のみです。 カタログの検索で取得するのは SkillSummary[] です。クライアントコンポーネントで Skill 全体を使うと、すべての README がすべての訪問者に送信されます。

クイックスタート

1. 境界となる契約、組織、カテゴリを記入します：adaptation.md。
2. 設定、カテゴリ、型を記述し、content/skills/ を用意します： data-model.md。
3. 同期処理をコピーして npm run skills:sync を接続します。実行するか、ネットワークに接続できない場合は assets/content/ をアプリにコピーします： sync.md。
4. frontmatter、レイアウト、Markdown、上流リーダーをコピーします：parsing.md。
5. 評価パーサーをコピーします：evals.md。
6. ローダーとバリデーターをコピーします：loader.md。
7. カタログと [slug] ページ、JSON-LD、サイトマップを追加します：routes.md。
8. コンポーネントを追加し、data-skill-* フックを使ってスタイルを設定します：ui.md。
9. vitest.config.ts と5つのテストファイルをコピーし、npm test を接続して、npm run typecheck および npm run build とともに実行します：testing.md。
10. 最終メッセージでは、README だけでなく、引き継ぎ事項も伝えます。config.ts に設定する組織とブランチ、スキルのリリースごとに npm run skills:sync を実行してその結果をコミットすること、スキルが約30個を超える場合に必要な GITHUB_TOKEN、デプロイ前に siteUrl を設定する必要があること（値はリテラルで、環境変数ではありません）、最初の実際の同期後にサンプルスキルを削除することを伝えます。次に読むのは extensions.md です。簡略化する前に、 provenance.md を読んでください。

リファレンスディレクトリ

シナリオ	トリガーキーワード	リファレンス
既存のアプリに組み込む	adapt, seam, organization, rename, host probe, categories, dependencies	adaptation.md
設定、カテゴリ、型、フォルダー	config, SKILLS_CATALOG, category, meta.md, Skill, SkillSummary, content/skills	data-model.md
スキルをリポジトリに取り込む	sync, skills:sync, GitHub, raw.githubusercontent.com, sha, GITHUB_TOKEN, rate limit, sync.json, local	sync.md
SKILL.md、README、変更履歴を読む	gray-matter, frontmatter, Date, heading, SKILL_LAYOUT, list, table, release, provenance, index table	parsing.md
プロンプトと評価の実行	evals, prompts.md, parseEval, result, partial, runNumber, latestRuns, runUrl, interventions	evals.md
カタログの読み込みと検証	getSkill, getAllSkills, cache, related, validateCatalog, warning, error	loader.md
ページ、メタデータ、JSON-LD、サイトマップ	route, page.tsx, generateStaticParams, dynamicParams, category page, TechArticle, BreadcrumbList, sitemap	routes.md
カード、検索、評価カード、Markdown	SkillCatalog, search, filter, EvalRuns, SkillMarkdown, relative links, urlTransform, data-skill	ui.md
テストとコンテンツバリデーター	vitest, npm test, catalog.test, fixture, example skill, alias	testing.md
リリース済みモジュールの範囲を超える機能	Markdown copy, llms.txt, price, call to action, assistant, eval collection, badges	extensions.md
テンプレートが以前の実装と異なる理由	provenance, audit, ledger, kept deliberately, added	provenance.md

兄弟スキルを掲載する Timerise Skills インデックスの一部です。