{"id":"48d8e76f-5622-4bb8-a2f8-2d67e7f54497","shortId":"hPXcmY","kind":"skill","title":"skill-repo","tagline":"Use when creating new skill repositories from scratch, standardizing or validating existing skill repo structure, setting up composer/release workflows for skills, configuring split licensing (MIT + CC-BY-SA-4.0), or fixing plugin.json / SKILL.md validation errors.","description":"# Skill Repository Structure Guide\n\nStandards for Netresearch skill repository layout and distribution.\n\n## Repository Structure\n\n```\n{repo-name}/\n├── .claude-plugin/plugin.json   # Plugin metadata (required)\n├── skills/{name}/SKILL.md       # AI instructions (required)\n├── README.md                    # Human docs (required)\n├── LICENSE-MIT                  # Code license (required)\n├── LICENSE-CC-BY-SA-4.0         # Content license (required)\n├── composer.json                # PHP distribution (required)\n├── references/                  # Extended docs for >500w content\n├── scripts/                     # Automation\n└── .github/workflows/\n    ├── release.yml              # Tag-triggered release\n    ├── validate.yml             # Caller for reusable validation\n    └── auto-merge-deps.yml      # Caller for dep auto-merge\n```\n\n## Licensing (Split Model)\n\n| Path pattern | License |\n|---|---|\n| `skills/**/*.md`, `references/**`, `README.md`, `docs/**` | CC-BY-SA-4.0 |\n| `scripts/**`, `.github/workflows/**`, `*.sh`, `*.py`, `*.php` | MIT |\n| `composer.json`, `plugin.json`, config files | MIT |\n\nSPDX: `(MIT AND CC-BY-SA-4.0)`. Copyright: `Netresearch DTT GmbH`. No bare `LICENSE` — split files only.\n\n## SKILL.md Frontmatter\n\n```yaml\n---\nname: skill-name          # lowercase, hyphens, max 64 chars\ndescription: \"Use when <trigger conditions>\"\n---\n```\n\nBody ≤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`](references/skill-quality.md). Put discovery/catalog fields in README or optional YAML, not frontmatter — [`references/skill-discovery-metadata.md`](references/skill-discovery-metadata.md).\n\n## plugin.json (`.claude-plugin/plugin.json`)\n\n```json\n{\n  \"name\": \"skill-name\",\n  \"version\": \"1.0.0\",\n  \"skills\": [\"./skills/skill-name\"],\n  \"license\": \"(MIT AND CC-BY-SA-4.0)\",\n  \"author\": {\"name\": \"Netresearch DTT GmbH\", \"url\": \"https://www.netresearch.de\"}\n}\n```\n\n## composer.json\n\nName **must match GitHub repo**. Type `ai-agent-skill`. No `version` field (from git tags). No `composer.lock`.\n\n```json\n{\n  \"name\": \"netresearch/{repo-name}\",\n  \"type\": \"ai-agent-skill\",\n  \"license\": \"(MIT AND CC-BY-SA-4.0)\",\n  \"require\": {\"netresearch/composer-agent-skill-plugin\": \"*\"},\n  \"extra\": {\"ai-agent-skill\": \"skills/{name}/SKILL.md\"}\n}\n```\n\n## Reusable Workflow Callers\n\nSkill repos MUST delegate CI to skill-repo-skill reusable workflows:\n\n```yaml\n# .github/workflows/validate.yml\nuses: netresearch/skill-repo-skill/.github/workflows/validate.yml@main\n```\n\nCallers: `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`.\n\n## Releasing\n\nBump 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`.\n\n## Installation\n\n1. **Marketplace**: `/plugin marketplace add netresearch/claude-code-marketplace`\n2. **Release**: Download to `~/.claude/skills/{name}/`\n3. **Composer**: `composer require netresearch/{repo-name}`\n4. **npm**: `npm i -D @netresearch/agent-skill-coordinator github:netresearch/{repo-name}`. Use `templates/package.json.template` (minimal `files` default; see `references/installation-methods.md`).\n\n## Validation\n\n```bash\nscripts/validate-skill.sh\n```\n\n## Cross-platform Compatibility\n\n`grep -E` (not `-P`); `bash` shebangs (zsh on macOS); `[[ ]]` for conditionals.\n\n## References (`references/`)\n\n**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\n\n## See Also\n\n[`agent-rules-skill`](https://github.com/netresearch/agent-rules-skill), [`agent-harness-skill`](https://github.com/netresearch/agent-harness-skill), [`retro-skill`](https://github.com/netresearch/retro-skill).\n\n---\n\n> **Contributing:** https://github.com/netresearch/skill-repo-skill","tags":["skill","repo","netresearch","agent-skills","ai-agent","open-standard"],"capabilities":["skill","source-netresearch","skill-skill-repo","topic-agent-skills","topic-ai-agent","topic-open-standard"],"categories":["skill-repo-skill"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/netresearch/skill-repo-skill/skill-repo","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add netresearch/skill-repo-skill","source_repo":"https://github.com/netresearch/skill-repo-skill","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (4,409 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:48.382Z","embedding":null,"createdAt":"2026-05-18T19:13:48.382Z","updatedAt":"2026-05-18T19:13:48.382Z","lastSeenAt":"2026-05-18T19:13:48.382Z","tsv":"'/.claude/plugins':361 '/.claude/skills':360,387 '/netresearch/agent-harness-skill),':493 '/netresearch/agent-rules-skill),':486 '/netresearch/retro-skill).':499 '/netresearch/skill-repo-skill':503 '/plugin':379 '/plugin.json':60,224 '/pr-quality':326 '/skill.md':66,296 '/skills/skill-name':233 '1':183,377 '1.0.0':231 '100':187 '2':383 '3':368,389 '300':188 '4':397 '4.0':33,85,134,153,241,286 '500':180 '500w':97 '536':184 '64':174 'action':333 'add':381 'agent':258,277,292,481,488 'agent-harness-skil':487 'agent-rules-skil':480 'ai':67,257,276,291 'ai-agent-skil':256,275,290 'also':479 'alway':362 'approv':373 'audit':203 'author':242 'auto':117,324 'auto-merg':116,323 'auto-merge-deps.yml':112,321 'autom':100 'bare':159 'bash':416,426 'bodi':179 'bump':338,353 'caller':108,113,299,317 'catalog':199 'cc':30,82,131,150,238,283 'cc-by-sa':29,130,149,237,282 'char':175,185 'checklist':469 'ci':304 'claud':58,222 'claude-plugin':57,221 'code':77 'compat':421 'compos':390,391,440 'composer-setup':439 'composer.json':89,141,249 'composer.lock':267 'composer/release':21 'condit':432 'config':143 'configur':25 'content':86,98 'contract':477 'contribut':500 'convent':200 'copyright':154 'creat':6 'cross':419 'cross-platform':418 'd':401 'default':412 'deleg':303 'dep':115 'descript':176,182 'disciplin':444 'discoveri':461,464 'discovery/catalog':209 'distribut':51,91,435 'doc':72,95,129 'docs/architecture.md':336 'domain':334 'done':466 'download':385 'dri':371 'dry-run':370 'dtt':156,245 'e':423 'edit':357 'error':39 'everi':191 'exist':15 'extend':94 'extra':289 'field':210,262 'file':144,162,411 'first':190 'fix':35 'frontmatt':165,217 'git':264 'github':253,403 'github.com':485,492,498,502 'github.com/netresearch/agent-harness-skill),':491 'github.com/netresearch/agent-rules-skill),':484 'github.com/netresearch/retro-skill).':497 'github.com/netresearch/skill-repo-skill':501 'github/workflows':101,136 'github/workflows/validate.yml':313 'gmbh':157,246 'grep':422 'guid':43 'har':489 'human':71 'hyphen':172 'inlin':332 'instal':358,376,437 'installation-method':436 'instruct':68 'integr':473 'json':225,268 'layout':49 'licens':27,75,78,81,87,119,124,160,234,279 'license-cc-by-sa':80 'license-mit':74 'lowercas':171 'maco':430 'main':316,342 'marketplac':378,380,472 'marketplace-integr':471 'match':252 'materi':476 'materialization-contract':475 'max':173 'md':126,193 'merg':118,325,340,355 'metadata':62,465 'method':438 'minim':410 'mit':28,76,140,145,147,235,280 'model':121 'monitor':348 'multi':366 'multi-repo':365 'must':194,251,302 'name':56,65,167,170,226,229,243,250,269,273,295,388,396,407 'need':369 'netresearch':46,155,244,270,393,404 'netresearch/.github':322 'netresearch/agent-skill-coordinator':402 'netresearch/claude-code-marketplace':382 'netresearch/composer-agent-skill-plugin':288 'netresearch/skill-repo-skill/.github/workflows/validate.yml':315 'never':356 'new':7 'npm':398,399 'option':214 'orphan':202 'p':425 'pariti':344 'path':122,359 'pattern':123 'php':90,139 'platform':420 'plugin':59,61,223 'plugin.json':36,142,220 'pr':339,354 'pull':328,341 'push':347 'put':208 'py':138 'qualiti':452,456 'reachabl':196 'readm':212,459 'readme-templ':458 'readme.md':70,128 'refer':93,127,192,433,434 'references/installation-methods.md':414 'references/release-discipline.md':375 'references/skill-discovery-metadata.md':218,219 'references/skill-quality.md':206,207 'releas':106,337,349,384,443 'release-disciplin':442 'release.yml':102,319 'repli':447 'repo':3,17,55,254,272,301,308,367,395,406 'repo-nam':54,271,394,405 'repo/readme':453 'repositori':9,41,48,52,455 'repository-quality-rul':454 'request':329 'requir':63,69,73,79,88,92,287,392 'retro':474,495 'retro-skil':494 'reusabl':110,297,310,335 'review':446 'review-repli':445 'rule':457,482 'run':372 'sa':32,84,133,152,240,285 'scratch':11 'script':99,135 'scripts/audit-skills.sh':204 'scripts/validate-skill.sh':417 'see':205,374,413,478 'set':19 'setup':441 'sh':137 'shebang':427 'sign':345 'skill':2,8,16,24,40,47,64,125,169,228,232,259,278,293,294,300,307,309,448,451,463,483,490,496 'skill-discovery-metadata':462 'skill-nam':168,227 'skill-qual':450 'skill-repo':1 'skill-repo-skil':306 'skill-skill-repo' 'skill.md':37,164,198 'source-netresearch' 'spdx':146 'split':26,120,161 'standard':12,44 'structur':18,42,53 'sync':470 'tag':104,265,346,350 'tag-trigg':103 'target':186,330 'templat':460 'templates/package.json.template':409 'text':449 'topic-agent-skills' 'topic-ai-agent' 'topic-open-standard' 'trigger':105,189 'type':255,274 'url':247 'use':4,177,314,327,408 'valid':14,38,111,415,468 'validate.yml':107,318 'validation-checklist':467 'verifi':343 'version':230,261 'word':181 'workflow':22,298,311 'worktre':364 'www.netresearch.de':248 'yaml':166,215,312 'zsh':428","prices":[{"id":"f08edcd5-4a4e-46ab-a91a-a1658f776f4e","listingId":"48d8e76f-5622-4bb8-a2f8-2d67e7f54497","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"netresearch","category":"skill-repo-skill","install_from":"skills.sh"},"createdAt":"2026-05-18T19:13:48.382Z"}],"sources":[{"listingId":"48d8e76f-5622-4bb8-a2f8-2d67e7f54497","source":"github","sourceId":"netresearch/skill-repo-skill/skill-repo","sourceUrl":"https://github.com/netresearch/skill-repo-skill/tree/main/skills/skill-repo","isPrimary":false,"firstSeenAt":"2026-05-18T19:13:48.382Z","lastSeenAt":"2026-05-18T19:13:48.382Z"}],"details":{"listingId":"48d8e76f-5622-4bb8-a2f8-2d67e7f54497","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"netresearch","slug":"skill-repo","github":{"repo":"netresearch/skill-repo-skill","stars":7,"topics":["agent-skills","ai-agent","open-standard"],"license":"other","html_url":"https://github.com/netresearch/skill-repo-skill","pushed_at":"2026-05-17T21:21:05Z","description":"Agent Skill guide for structuring skill repositories - multi-channel distribution | Claude Code compatible","skill_md_sha":"86621cf0646e859044988266c1098b6dbbf2e0f5","skill_md_path":"skills/skill-repo/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/netresearch/skill-repo-skill/tree/main/skills/skill-repo"},"layout":"multi","source":"github","category":"skill-repo-skill","frontmatter":{"name":"skill-repo","license":"(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0","description":"Use when creating new skill repositories from scratch, standardizing or validating existing skill repo structure, setting up composer/release workflows for skills, configuring split licensing (MIT + CC-BY-SA-4.0), or fixing plugin.json / SKILL.md validation errors.","compatibility":"Requires bash 4.3+, python3."},"skills_sh_url":"https://skills.sh/netresearch/skill-repo-skill/skill-repo"},"updatedAt":"2026-05-18T19:13:48.382Z"}}