skill-repo

スキルリポジトリ構成ガイド

リポジトリ構成

{repo-name}/
├── plugin.json                  # portable manifest
├── .claude-plugin/plugin.json   # generated
├── skills/{name}/SKILL.md       # the control plane
├── README.md                    # human docs
├── LICENSE-MIT                  # code
├── LICENSE-CC-BY-SA-4.0         # content
├── composer.json                # PHP distribution
├── references/                  # detail, loaded on demand
├── scripts/                     # executables, never loaded
└── .github/workflows/
    ├── release.yml              # tag-triggered
    ├── validate.yml             # validation caller
    └── auto-merge-deps.yml      # dep auto-merge caller

ライセンス（分割モデル）

パスのパターン	ライセンス
skills/**/*.md, references/**, README.md, docs/**	CC-BY-SA-4.0
scripts/**, .github/workflows/**, *.sh, *.py, *.php	MIT
composer.json, plugin.json, 設定ファイル	MIT

SPDX：(MIT AND CC-BY-SA-4.0)。著作権者：Netresearch DTT GmbH。単独の LICENSE はなく、分割ファイルのみです。

SKILL.md のフロントマター

---
name: skill-name
description: "Use when <trigger conditions>"
---

予算（仕様）：name は64文字以下で、ハイフンの重複や先頭・末尾のハイフンは不可。ディレクトリ名と一致させます。description は1024文字以下で、500文字を超えたら警告します。これはドキュメントではなくルーターです。本文は500行以下で、300行で警告します。compatibility は500文字以下で、通常は省略します。

フラットな探索：参照ファイルは1階層までです。SKILL.md には、すべての references/*.md と、すべての scripts/ 内の実行可能ファイルを記載します。100行を超える場合は ## Contents を設けます。根拠とトリガーの評価については、skill-architecture を参照してください。監査には、リポジトリのトップレベル scripts/ にある audit-skills.sh を使用します（スキルには同梱されません）。

マニフェスト

ルートの plugin.json（Agent Plugins 1.0.0、許可されるフィールドは固定）が信頼できる唯一の情報源です。sync-plugin-manifest.sh は Claude 専用キーを追加して .claude-plugin/plugin.json を生成します。詳しくは agent-plugins-compat を参照してください。

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "skill-name",
  "version": "1.0.0",
  "license": "(MIT AND CC-BY-SA-4.0)",
  "author": {"name": "Netresearch DTT GmbH", "url": "https://www.netresearch.de"}
}

composer.json

名前はGitHub リポジトリと一致している必要があります。タイプは ai-agent-skill です。version フィールドは指定しません（git タグから取得します）。composer.lock は作成しません。

{
  "name": "netresearch/{repo-name}",
  "type": "ai-agent-skill",
  "license": "(MIT AND CC-BY-SA-4.0)",
  "require": {"netresearch/composer-agent-skill-plugin": "*"},
  "extra": {"ai-agent-skill": "skills/{name}/SKILL.md"}
}

再利用可能なワークフローの呼び出し元

スキルリポジトリは CI を skill-repo-skill の再利用可能なワークフローに委譲する必要があります。

# .github/workflows/validate.yml
uses: netresearch/skill-repo-skill/.github/workflows/validate.yml@main

呼び出し元：validate.yml、release.yml（このリポジトリ）；auto-merge-deps.yml（netresearch/.github）。Auto-merge/pr-quality は pull_request_target を使用します。インラインの Actions は使用しません。ドメイン別の再利用可能なワークフローについては docs/ARCHITECTURE.md を参照してください。

リリース

ルートの plugin.json のバージョンを更新 → 同期 → PR → マージ → main をプル → 同期状態を確認 → 署名付きタグを作成 → プッシュ → Release を監視します。バージョン更新 PR がマージされてからタグを作成してください。 複数リポジトリ（3つ超）の場合は、ドライランと承認が必要です。0.x → 1.0.0 への移行は、計画を書き換えるのではなく STABILIZE の行を経由します。インストール済みのパスは決して編集しないでください。release-discipline

インストール

Marketplace、リリースのダウンロード、Composer、npm のコマンドと、npm の files のデフォルト設定については installation-methods を参照してください。

検証

scripts/validate-skill.sh（レイアウト、マニフェスト、予算、フラットな探索）。シェルの移植性については authoring-ci-gotchas を参照してください。

検索しやすいよう、以下の名前をここに記載します：bump-version.sh、check-version-parity.sh、sync-plugin-manifest.sh、roll-changelog.py、fleet-release-github.sh、migrate-licensing.sh、validate-evals.sh。各スクリプトには --help があります。

参考資料（references/）

agent-plugins-compat · installation-methods · plugin-hooks · composer-setup · release-discipline · review-replies · skill-quality · repository-quality-rules · readme-template · skill-discovery-metadata · validation-checklist · marketplace-integration · materialization-contract · authoring-ci-gotchas · skill-retirement

---

貢献: https://github.com/netresearch/skill-repo-skill