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, writing or validating skill evals, selection tests or captured agent evidence, or releasing a skill version (version bump, tagging).
How do I install this agent skill?
npx skills add https://github.com/netresearch/skill-repo-skill --skill skill-repoIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a legitimate repository management tool for maintaining and validating AI agent skill repositories. It provides automated scripts for versioning, manifest synchronization, and structural checks. All behaviors are consistent with its primary purpose of development automation.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/netresearch/skill-repo-skill/skill-repo">View skill-repo on skillZs</a>