Claude Skill

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

LLM Mart · 0 points · 3 views 54 listing impressions 0 install-command copies
Download netresearch-skill-repo-skill-skills_skill-repo-d3ce165.zip · 222 KB

Install

skills CLI npx skills add https://github.com/netresearch/skill-repo-skill/tree/main/skills/skill-repo
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install netresearch-skill-repo-skill@llmmart
Git 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.

No comments yet.

Reviews (0)

No reviews yet.