skill-repo

Skill Repository 结构指南

Repository 结构

{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 Frontmatter

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

限制（规范）：name ≤64 个字符，不得包含连字符重复或位于首尾，并且必须与其目录名一致。description ≤1024 个字符，超过 500 个字符时发出警告 — 它是路由器，不是文档。正文 ≤500 行，达到 300 行时发出警告。compatibility ≤500 个字符，通常省略。

扁平发现：引用文件仅深入一层；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-plugin/plugin.json 以及仅供 Claude 使用的键 — 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（目录布局、清单、限制、扁平发现）。Shell 可移植性：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