skill-repo
Use when creating skill repositories, standardizing or validating skill repo structure, setting up composer/release workflows, configuring split licensing (MIT + CC-BY-SA-4.0), fixing plugin.json / SKILL.md validation or version-parity errors, or releasing a skill version (versio
Install
npx skills add https://github.com/netresearch/skill-repo-skill/tree/main/skills/skill-repo
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install netresearch-skill-repo-skill@llmmart
git clone https://github.com/netresearch/skill-repo-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole netresearch/skill-repo-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Skill Repository Structure Guide
Repository Structure
{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
Licensing (Split Model)
| Path pattern | License |
|---|---|
skills/**/*.md, references/**, README.md, docs/** |
CC-BY-SA-4.0 |
scripts/**, .github/workflows/**, *.sh, *.py, *.php |
MIT |
composer.json, plugin.json, config files |
MIT |
SPDX: (MIT AND CC-BY-SA-4.0). Copyright: Netresearch DTT GmbH. No bare LICENSE — split files only. Internal repositories keep their author's licence (LICENSE_MODEL=declared).
SKILL.md Frontmatter
---
name: skill-name
description: "Use when <trigger conditions>"
---
Budgets (spec): name ≤64, no doubled/edge hyphen, matches its directory. description ≤1024, warn past 500 — a router, not documentation. Body ≤500 lines, warn at 300. compatibility ≤500, usually omit.
Flat discovery: references one level deep; SKILL.md names every references/*.md and every scripts/ executable; ## Contents past 100 lines. Rationale and trigger evals: skill-architecture. Audit: audit-skills.sh in the repository's top-level scripts/ (not shipped with the skill).
Manifests
Root plugin.json (Agent Plugins 1.0.0, closed field set) is the source of truth; sync-plugin-manifest.sh generates .claude-plugin/plugin.json plus Claude-only keys — 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
Name must match GitHub repo. Type ai-agent-skill. No version field (from git tags). No 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"}
}
Reusable Workflow Callers
Skill repos MUST delegate CI to skill-repo-skill reusable workflows:
# .github/workflows/validate.yml
uses: netresearch/skill-repo-skill/.github/workflows/validate.yml@main
Callers: validate.yml, release.yml (here); auto-merge-deps.yml (netresearch/.github). Auto-merge/pr-quality use pull_request_target. No inline Actions. Domain reusables: docs/ARCHITECTURE.md.
Releasing
Bump root plugin.json → sync → PR → merge → pull main → verify parity → signed tag → push → monitor Release. Tag only after bump PR merges. Multi-repo (>3) needs dry-run + approval; 0.x → 1.0.0 goes through STABILIZE rows, not retyped plans. Never edit installed paths — release-discipline.
Installation
Marketplace, release download, Composer, npm — commands and the npm files default in installation-methods.
Validation
scripts/validate-skill.sh (layout, manifests, budgets, flat discovery, Python scripts on 3.11+ through uv run). Shell portability: authoring-ci-gotchas.
Validate the unpacked/installed payload too: a shared reference that exists in the source tree may be absent from a standalone skill. Supply runtime resources or explicit optional fallbacks; never count a missing check as success.
For behavior changes, separate structural checks, normal skill selection, recorded tools and independent task outcomes. From the run directory, use agent-evidence and uv run ${CLAUDE_SKILL_DIR}/scripts/validate-agent-evidence.py RUN.json for captured ATIF/Claude evidence; errors/timeouts are incomplete, including negative selection cases. The text-only A/B runner cannot establish routing or tool execution.
Named here so they are findable: bump-version.sh, check-version-parity.sh, sync-plugin-manifest.sh, roll-changelog.py, fleet-release-github.sh, migrate-licensing.sh, validate-evals.sh, validate-agent-evidence.py — each with --help.
References (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 · agent-evidence · authoring-ci-gotchas · skill-retirement
Contributing: https://github.com/netresearch/skill-repo-skill
Files (skill-repo-skill)
-
evals
-
evals.json 31.3 KB
Loading… -
eval_queries.json 1.2 KB
Loading…
-
-
references
-
agent-evidence.md 7.2 KB
Loading… -
agent-plugins-compat.md 6.7 KB
Loading… -
authoring-ci-gotchas.md 19.3 KB
Loading… -
composer-setup.md 10.9 KB
Loading… -
installation-methods.md 11.6 KB
Loading… -
marketplace-integration.md 5.9 KB
Loading… -
materialization-contract.md 19.1 KB
Loading… -
plugin-hooks.md 5.9 KB
Loading… -
readme-template.md 6.1 KB
Loading… -
release-discipline.md 63.8 KB
Loading… -
repository-quality-rules.md 20.9 KB
Loading… -
review-replies.md 6.6 KB
Loading… -
skill-architecture.md 21.6 KB
Loading… -
skill-discovery-metadata.md 5 KB
Loading… -
skill-quality.md 25.7 KB
Loading… -
skill-retirement.md 4.1 KB
Loading… -
validation-checklist.md 13 KB
Loading…
-
-
scripts
-
bump-version.sh 7.3 KB
Loading… -
check-version-parity.sh 4.7 KB
Loading… -
fleet-release-common.sh 69.8 KB
Loading… -
fleet-release-github.sh 34 KB
Loading… -
fleet-repos-github.txt 2.8 KB
Loading… -
migrate-licensing.sh 9.1 KB
Loading… -
roll-changelog.py 19.2 KB
Loading… -
sync-plugin-manifest.sh 4.6 KB
Loading… -
validate-agent-evidence.py 14 KB
Loading… -
validate-evals.sh 28.6 KB
Loading… -
validate-skill.sh 66.5 KB
Loading…
-
-
templates
-
.github
-
workflows
-
npm-pack-smoke.yml.template 1.2 KB · in bundle
-
validate.yml.template 547 B · in bundle
-
-
-
auto-merge-deps.yml.template 237 B · in bundle
-
composer.json.template 417 B · in bundle
-
LICENSE-CC-BY-SA-4.0.template 839 B · in bundle
-
LICENSE-MIT.template 1.1 KB · in bundle
-
package.json.template 1.8 KB · in bundle
-
plugin.json.template 362 B · in bundle
-
pr-quality.yml.template 834 B · in bundle
-
pre-commit.template 434 B · in bundle
-
README.md.template 6.6 KB · in bundle
-
release.yml.template 1.8 KB · in bundle
-
-
checkpoints.yaml 16.4 KB
Loading… -
SKILL.md 6.8 KB
--- # SPDX-License-Identifier: CC-BY-SA-4.0 # SPDX-FileCopyrightText: Netresearch DTT GmbH name: skill-repo description: "Use when creating skill repositories, standardizing or validating skill repo structure, setting up composer/release workflows, configuring split licensing (MIT + CC-BY-SA-4.0), fixing plugin.json / SKILL.md validation or version-parity errors, writing or validating skill evals, selection tests or captured agent evidence, or releasing a skill version (version bump, tagging)." license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0" compatibility: "Requires bash 4.3+, python3 3.11+, and uv (runs the Python scripts)." metadata: author: Netresearch DTT GmbH version: "4.0.0" repository: https://github.com/netresearch/skill-repo-skill allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/*) Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*) Bash(uv run ${CLAUDE_SKILL_DIR}/scripts/*) Bash(skills/skill-repo/scripts/*) Bash(bash skills/skill-repo/scripts/*) Read Write Glob Grep --- # Skill Repository Structure Guide ## Repository Structure ``` {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 ``` ## Licensing (Split Model) | Path pattern | License | |---|---| | `skills/**/*.md`, `references/**`, `README.md`, `docs/**` | CC-BY-SA-4.0 | | `scripts/**`, `.github/workflows/**`, `*.sh`, `*.py`, `*.php` | MIT | | `composer.json`, `plugin.json`, config files | MIT | SPDX: `(MIT AND CC-BY-SA-4.0)`. Copyright: `Netresearch DTT GmbH`. No bare `LICENSE` — split files only. Internal repositories keep their author's licence (`LICENSE_MODEL=declared`). ## SKILL.md Frontmatter ```yaml --- name: skill-name description: "Use when <trigger conditions>" --- ``` **Budgets** (spec): `name` ≤64, no doubled/edge hyphen, matches its directory. `description` ≤1024, warn past 500 — a router, not documentation. Body ≤500 lines, warn at 300. `compatibility` ≤500, usually omit. **Flat discovery**: references one level deep; SKILL.md names every `references/*.md` and every `scripts/` executable; `## Contents` past 100 lines. Rationale and trigger evals: [skill-architecture](references/skill-architecture.md). Audit: `audit-skills.sh` in the repository's top-level `scripts/` (not shipped with the skill). ## Manifests Root `plugin.json` ([Agent Plugins 1.0.0](https://agent-plugins.org), closed field set) is the source of truth; `sync-plugin-manifest.sh` generates `.claude-plugin/plugin.json` plus Claude-only keys — [agent-plugins-compat](references/agent-plugins-compat.md). ```json { "$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 Name **must match GitHub repo**. Type `ai-agent-skill`. No `version` field (from git tags). No `composer.lock`. ```json { "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"} } ``` ## Reusable Workflow Callers Skill repos MUST delegate CI to skill-repo-skill reusable workflows: ```yaml # .github/workflows/validate.yml uses: netresearch/skill-repo-skill/.github/workflows/validate.yml@main ``` Callers: `validate.yml`, `release.yml` (here); `auto-merge-deps.yml` (`netresearch/.github`). Auto-merge/pr-quality use `pull_request_target`. No inline Actions. Domain reusables: `docs/ARCHITECTURE.md`. ## Releasing Bump root `plugin.json` → sync → PR → merge → pull main → verify parity → signed tag → push → monitor Release. **Tag only after bump PR merges.** Multi-repo (>3) needs dry-run + approval; 0.x → 1.0.0 goes through `STABILIZE` rows, not retyped plans. Never edit installed paths — [release-discipline](references/release-discipline.md). ## Installation Marketplace, release download, Composer, npm — commands and the npm `files` default in [installation-methods](references/installation-methods.md). ## Validation `scripts/validate-skill.sh` (layout, manifests, budgets, flat discovery, Python scripts on 3.11+ through `uv run`). Shell portability: [authoring-ci-gotchas](references/authoring-ci-gotchas.md). Validate the unpacked/installed payload too: a shared reference that exists in the source tree may be absent from a standalone skill. Supply runtime resources or explicit optional fallbacks; never count a missing check as success. For behavior changes, separate structural checks, normal skill selection, recorded tools and independent task outcomes. From the run directory, use [agent-evidence](references/agent-evidence.md) and `uv run ${CLAUDE_SKILL_DIR}/scripts/validate-agent-evidence.py RUN.json` for captured ATIF/Claude evidence; errors/timeouts are incomplete, including negative selection cases. The text-only A/B runner cannot establish routing or tool execution. Named here so they are findable: `bump-version.sh`, `check-version-parity.sh`, `sync-plugin-manifest.sh`, `roll-changelog.py`, `fleet-release-github.sh`, `migrate-licensing.sh`, `validate-evals.sh`, `validate-agent-evidence.py` — each with `--help`. ## References (`references/`) [agent-plugins-compat](references/agent-plugins-compat.md) · [installation-methods](references/installation-methods.md) · [plugin-hooks](references/plugin-hooks.md) · [composer-setup](references/composer-setup.md) · [release-discipline](references/release-discipline.md) · [review-replies](references/review-replies.md) · [skill-quality](references/skill-quality.md) · [repository-quality-rules](references/repository-quality-rules.md) · [readme-template](references/readme-template.md) · [skill-discovery-metadata](references/skill-discovery-metadata.md) · [validation-checklist](references/validation-checklist.md) · [marketplace-integration](references/marketplace-integration.md) · [materialization-contract](references/materialization-contract.md) · [agent-evidence](references/agent-evidence.md) · [authoring-ci-gotchas](references/authoring-ci-gotchas.md) · [skill-retirement](references/skill-retirement.md) --- > **Contributing:** <https://github.com/netresearch/skill-repo-skill>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.