Agent Skill: Guide for structuring Netresearch skill repositories. Use when creating skills, standardizing repos, or setting up composer/release workflows. By Netresearch.
Standards for Netresearch skill repository layout and distribution.
{repo-name}/
├── .claude-plugin/plugin.json # Plugin metadata (required)
├── skills/{name}/SKILL.md # AI instructions (required)
├── README.md # Human docs (required)
├── LICENSE-MIT # Code license (required)
├── LICENSE-CC-BY-SA-4.0 # Content license (required)
├── composer.json # PHP distribution (required)
├── references/ # Extended docs for >500w content
├── scripts/ # Automation
└── .github/workflows/
├── release.yml # Tag-triggered release
├── validate.yml # Caller for reusable validation
└── auto-merge-deps.yml # Caller for dep auto-merge
| 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.
---
name: skill-name # lowercase, hyphens, max 64 chars
description: "Use when <trigger conditions>"
---
Body ≤500 words; description ≤1,536 chars (target 100–300, trigger first). Every references/*.md must be reachable from SKILL.md (catalog conventions — no orphans). Audit: scripts/audit-skills.sh. See references/skill-quality.md. Put discovery/catalog fields in README or optional YAML, not frontmatter — references/skill-discovery-metadata.md.
.claude-plugin/plugin.json){
"name": "skill-name",
"version": "1.0.0",
"skills": ["./skills/skill-name"],
"license": "(MIT AND CC-BY-SA-4.0)",
"author": {"name": "Netresearch DTT GmbH", "url": "https://www.netresearch.de"}
}
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"}
}
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.
Bump PR → merge → pull main → verify parity → signed tag → push → monitor Release. Tag only after bump PR merges. Never edit installed paths (~/.claude/skills/**, ~/.claude/plugins/**); always the worktree. Multi-repo (>3) needs dry-run + approval. See references/release-discipline.md.
/plugin marketplace add netresearch/claude-code-marketplace~/.claude/skills/{name}/composer require netresearch/{repo-name}npm i -D @netresearch/agent-skill-coordinator github:netresearch/{repo-name}. Use templates/package.json.template (minimal files default; see references/installation-methods.md).scripts/validate-skill.sh
grep -E (not -P); bash shebangs (zsh on macOS); [[ ]] for conditionals.
references/)Distribution: installation-methods, composer-setup, release-discipline, review-replies · SKILL text: skill-quality · Repo/README: repository-quality-rules, readme-template · Discovery: skill-discovery-metadata · Done: validation-checklist · Sync: marketplace-integration · Retro: materialization-contract
agent-rules-skill, agent-harness-skill, retro-skill.
Contributing: https://github.com/netresearch/skill-repo-skill
