netresearch 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.
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. 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). Shell portability: authoring-ci-gotchas.
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 — each with --help.
References (references/)
agent-plugins-compat · installation-methods · 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
Contributing: https://github.com/netresearch/skill-repo-skill