Skill Repo

Skill Repository Structure Guide

Standards for Netresearch skill repository layout and distribution.

Repository Structure

{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

Licensing (Split Model)

SPDX: (MIT AND CC-BY-SA-4.0). Copyright: Netresearch DTT GmbH. No bare LICENSE — split files only.

SKILL.md Frontmatter

---
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`.

plugin.json (.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"}
}

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 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.

Installation

1. Marketplace: /plugin marketplace add netresearch/claude-code-marketplace 2. Release: Download to ~/.claude/skills/{name}/ 3. Composer: composer require netresearch/{repo-name} 4. 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).

Validation

scripts/validate-skill.sh

Cross-platform Compatibility

grep -E (not -P); bash shebangs (zsh on macOS); [[ ]] for conditionals.

References (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

See Also

`agent-rules-skill`, `agent-harness-skill`, `retro-skill`.

---

Contributing: <https://github.com/netresearch/skill-repo-skill>

Composer Setup for Skills

Guide for adding Composer distribution to Netresearch skills.

When to Add composer.json

Add composer.json to ALL skills EXCEPT those explicitly targeting non-PHP ecosystems.

composer.json Structure

Basic Structure

{
  "name": "netresearch/{skill-name}-skill",
  "description": "{Skill description from SKILL.md}",
  "type": "ai-agent-skill",
  "license": "(MIT AND CC-BY-SA-4.0)",
  "authors": [
    {
      "name": "Netresearch DTT GmbH",
      "email": "plugins@netresearch.de",
      "homepage": "https://www.netresearch.de/",
      "role": "Manufacturer"
    }
  ],
  "require": {
    "netresearch/composer-agent-skill-plugin": "*"
  },
  "extra": {
    "ai-agent-skill": "SKILL.md"
  }
}

Key Fields

Package Naming Convention

• Rule: composer name = GitHub repo name (netresearch/{repo-name})
• All skill repos are named *-skill on GitHub
• Examples:
• Repo netresearch/typo3-docs-skill → composer name netresearch/typo3-docs-skill
• Repo netresearch/jira-skill → composer name netresearch/jira-skill

Multi-Skill Packages

For packages containing multiple skills:

{
  "name": "netresearch/{name}-skill",
  "type": "ai-agent-skill",
  "extra": {
    "ai-agent-skill": [
      "skills/skill-one/SKILL.md",
      "skills/skill-two/SKILL.md"
    ]
  }
}

Example: jira-skill

{
  "name": "netresearch/jira-skill",
  "extra": {
    "ai-agent-skill": [
      "skills/jira-communication/SKILL.md",
      "skills/jira-syntax/SKILL.md"
    ]
  }
}

Publishing to Packagist

Prerequisites

1. GitHub repository is public 2. composer.json is valid 3. Packagist account linked to GitHub

Steps

1. Create version tag:

   git tag v1.0.0
   git push --tags

2. Register on Packagist:

• Go to https://packagist.org/packages/submit
• Enter repository URL
• Submit

3. Enable auto-update:

• Configure GitHub webhook for Packagist
• Or use GitHub Actions integration

Files to NOT Include

Never add these to skill repos:

• composer.lock - Locks are for applications, not libraries
• vendor/ - Dependencies installed by users

Validation

Check composer.json validity:

# Syntax check
composer validate

# Check type
grep '"type"' composer.json | grep "ai-agent-skill"

# Check plugin requirement
grep "composer-agent-skill-plugin" composer.json

Integration with Plugin

The composer-agent-skill-plugin automatically:

1. Discovers installed ai-agent-skill packages 2. Parses SKILL.md frontmatter 3. Generates AGENTS.md index 4. Provides composer list-skills command 5. Provides composer read-skill {name} command

Troubleshooting

"Package not found"

• Ensure package is published on Packagist
• Check package name matches exactly
• Run composer clear-cache

"Plugin not activated"

When prompted, allow the plugin:

Do you trust "netresearch/composer-agent-skill-plugin"? [y,n,d,?]

Or pre-authorize in composer.json:

{
  "config": {
    "allow-plugins": {
      "netresearch/composer-agent-skill-plugin": true
    }
  }
}

"SKILL.md not found"

• Verify path in extra.ai-agent-skill
• Paths must be relative from package root
• Absolute paths are rejected for security

Installation Methods

Four methods for installing Netresearch skills.

Method 1: Netresearch Marketplace (Recommended)

The marketplace aggregates all Netresearch skills in one place.

Setup

/plugin marketplace add netresearch/claude-code-marketplace

Usage

# Browse available plugins
/plugin

# Install specific skill
/plugin install {skill-name}

Benefits

• Curated collection
• Automatic updates via sync
• Easy discovery
• No manual file management

Method 2: Download Release

Download packaged skill files from GitHub Releases.

Steps

1. Go to skill's GitHub repository 2. Navigate to Releases page 3. Download latest .zip or .tar.gz 4. Extract to ~/.claude/skills/{skill-name}/

Package Contents

Release packages contain only skill-relevant files:

• SKILL.md
• LICENSE-MIT
• LICENSE-CC-BY-SA-4.0
• references/
• scripts/
• assets/
• templates/

Excluded from Packages

• README.md (human documentation)
• .github/ (CI/CD)
• composer.json (separate distribution)
• Dev configuration files

Method 3: Composer (PHP Projects)

For PHP projects, install skills as Composer packages.

Prerequisites

1. PHP 8.2+ 2. Composer 2.1+ 3. composer-agent-skill-plugin

Installation

# Install the plugin first (once per project)
composer require netresearch/composer-agent-skill-plugin

# Install skills
composer require netresearch/{repo-name}

How It Works

1. Plugin discovers packages with type ai-agent-skill 2. Generates AGENTS.md index in project root 3. Skills available via composer read-skill {name}

Benefits

• Version management via Composer
• Dependency resolution
• Project-specific skill sets
• Easy updates with composer update

Method 4: npm (Node Projects)

For Node.js / TypeScript projects, install skills as npm packages discovered by @netresearch/agent-skill-coordinator.

Prerequisites

1. Node.js 18+ and npm 9+ (or pnpm/yarn equivalent) 2. `@netresearch/agent-skill-coordinator` — peer dependency that scans node_modules and registers skills in AGENTS.md

Installation

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/{repo-name}

For pnpm, allowlist the coordinator's postinstall so it can write AGENTS.md:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

How It Works

1. Coordinator's postinstall walks node_modules for packages declaring aiAgentSkill: skills/<name>/SKILL.md 2. Validates frontmatter, then writes a <skills_system> block into the project's AGENTS.md 3. Skill content is then visible to any agent reading AGENTS.md

What ships in the npm tarball

The files allowlist in package.json controls what npm packs. The default in templates/package.json.template is intentionally minimal — the skill payload (skills/<name>/), plugin metadata (.claude-plugin/), the canonical agent rules entry-point (AGENTS.md), licenses, and README.md:

{
  "files": [
    "skills/{skill-name}/",
    ".claude-plugin/",
    "AGENTS.md",
    "LICENSE-MIT",
    "LICENSE-CC-BY-SA-4.0",
    "README.md"
  ]
}

When to add a top-level data dir

Add a top-level dir to files only if your installed skill code reads from it at runtime (e.g. via $ROOT/<dir>/... or ../<dir>/... from a script under skills/<name>/scripts/). Common runtime data dirs:

• catalog/ — cli-tools-skill ships this because its installer scripts read $ROOT/catalog/*.json.
• hooks/ — Claude Code's plugin loader reads hooks/hooks.json. Ship it if your skill ships PreToolUse/PostToolUse hooks.
• commands/ — slash command definitions. Ship if present.
• outputStyles/ — output style definitions. Ship if present.
• assets/ — referenced assets (images, configs). Ship if your skill content references them at install paths.

When NOT to add a top-level dir

• Top-level `scripts/` is typically repo-maintenance only (e.g. verify-harness.sh, generate-dashboard.sh). Keep it out unless your installed skill scripts read from $ROOT/scripts/ at runtime. Runtime scripts belong under skills/<name>/scripts/ (already covered by skills/<name>/).
• Example: context7-skill does NOT ship top-level scripts/ because its only file is verify-harness.sh (repo-maintenance).
• Example: cli-tools-skill DOES ship catalog/ because its installer scripts read $ROOT/catalog/*.json.
• Build/ — dev-only build artifacts. Never ship.
• evals/, docs/ — repo-internal. Never ship.
• .github/, lint configs (.markdownlint*, .yamllint*), .envrc — repo-internal. Never ship.

Heuristic when looking at a top-level dir:

package-root/
  catalog/   # consumed at runtime  -> MUST be in files
  Build/     # dev-only build artifacts -> DO NOT include
  scripts/   # inspect: runtime or repo-maintenance? include only if runtime

CI safeguard

templates/.github/workflows/npm-pack-smoke.yml.template is a ready-to-copy GitHub Actions workflow that runs npm pack --dry-run on every PR and asserts:

1. No internal leakage — fails if the tarball contains .github/, evals/, docs/, Build/, verify-harness.sh, lint configs, etc. 2. Runtime-referenced dirs are present — greps skills/*/scripts/ for $ROOT/<dir> and ../<dir>/ references; if a script reads $ROOT/catalog but catalog/ is missing from the tarball, the job fails.

Copy it into .github/workflows/npm-pack-smoke.yml in your skill repo. It catches both kinds of files-allowlist mistakes (over-inclusion and under-inclusion) before they ship.

"private": true on 0.0.0-source

Skill repos use the placeholder version 0.0.0-source and must set "private": true to guard against accidental npm publish of the placeholder. Real publishes (when/if added later) flip private to false (or remove it) at release time and set a real semver.

Limitation: SKILL.md content only

The npm path registers only SKILL.md content into AGENTS.md. Slash commands (defined under commands/) and PreToolUse / PostToolUse hooks (defined under .claude-plugin/) are loaded by Claude Code's plugin mechanism — not by the coordinator scanning node_modules. Repos that ship those features should document this explicitly in their README (a > **Limitation:** callout immediately after the npm install snippet) so consumers know they need the marketplace install for the full skill.

Benefits

• Lock-file pinning via package-lock.json / pnpm-lock.yaml
• Renovate / Dependabot can bump skill versions like any other dep
• No PHP / Composer required for Node-only projects

Choosing a Method

Directory Locations

Marketplace Integration

How skills are synced to the Netresearch Claude Code Marketplace.

Separation from skill-repo rules

• This document explains sync mechanics and source-vs-synced files.
• Discovery, SEO, catalog completeness, and orphan rules for the marketplace Hub live only in the marketplace repository: [`AGENTS.md` in `netresearch/claude-code-marketplace`](https://github.com/netresearch/claude-code-marketplace/blob/main/AGENTS.md).
• Single skill repository quality (README sections, agents/openai.yaml, GitHub Description/Topics, discovery YAML) lives here in skill-repo-skill — see `repository-quality-rules.md`, `readme-template.md`, `skill-discovery-metadata.md`.

Do not duplicate marketplace governance prose in skill-repo references; link instead.

Overview

The claude-code-marketplace aggregates skills from individual repositories via automated sync workflows.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  skill-repo-1   │     │  skill-repo-2   │     │  skill-repo-N   │
│  (source)       │     │  (source)       │     │  (source)       │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                                 ▼
                    ┌────────────────────────┐
                    │  claude-code-marketplace│
                    │  (aggregator)           │
                    │                         │
                    │  skills/                │
                    │  ├── skill-1/           │
                    │  ├── skill-2/           │
                    │  └── skill-N/           │
                    └────────────────────────┘

Sync Workflow

Automatic Sync (Scheduled)

• Frequency: Weekly (Monday 2 AM UTC)
• Trigger: GitHub Actions schedule
• Process:

1. Clone each source repository 2. Extract semantic version from .claude-plugin/plugin.json 3. Append commit date for versioning 4. Copy skill files to skills/ directory 5. Update marketplace metadata

On-Demand Sync

Source repositories can trigger immediate sync via:

# notify-marketplace.yml in source repo
name: Notify Marketplace

on:
  release:
    types: [published]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger marketplace sync
        run: |
          gh workflow run sync-skills.yml \
            --repo netresearch/claude-code-marketplace
        env:
          GH_TOKEN: ${{ secrets.MARKETPLACE_SYNC_TOKEN }}

Adding a Skill to Marketplace

Prerequisites

1. Skill repository follows standard structure 2. .claude-plugin/plugin.json has valid version 3. Repository is public

Configuration

Add skill to .sync-config.json in marketplace repo:

{
  "skills": [
    {
      "name": "my-skill",
      "repo": "netresearch/my-skill",
      "path": "skills/my-skill"
    }
  ]
}

Versioning

Marketplace versions combine:

• Semantic version from .claude-plugin/plugin.json
• Last commit date

Example: 1.2.3-20251021

Sync Workflow Details

Files Synced

From source repository:

• SKILL.md
• references/
• scripts/
• assets/
• templates/
• LICENSE-MIT
• LICENSE-CC-BY-SA-4.0

Files NOT Synced

• README.md (marketplace has its own)
• .github/
• composer.json
• Dev configuration files
• claudedocs/

Marketplace Metadata

Updated in .claude-plugin/marketplace.json:

{
  "skills": {
    "my-skill": {
      "version": "1.2.3-20251021",
      "description": "Skill description",
      "source": "netresearch/my-skill"
    }
  }
}

User Installation

Add Marketplace

/plugin marketplace add netresearch/claude-code-marketplace

Browse Skills

/plugin

Install Skill

/plugin install {skill-name}

Benefits of Marketplace Distribution

Troubleshooting

Skill Not Appearing

1. Check .sync-config.json includes the skill 2. Verify source repo is accessible 3. Check sync workflow logs 4. Ensure SKILL.md has valid frontmatter

Outdated Version

1. Check last sync time in marketplace README 2. Trigger manual sync if needed 3. Verify source repo has new commits/releases

Sync Failures

Common causes:

• Invalid SKILL.md frontmatter
• Missing required files
• Network/API issues
• Permission problems

Check GitHub Actions logs in marketplace repo.

Materialization Contract

How external tools (notably retro-skill) materialize skill improvements or new skills by submitting PRs to skill repositories that follow skill-repo-skill conventions.

Scope

This contract covers two destinations from retro-skill's destination taxonomy:

• `skill-update` — PR against an existing skill repo
• `new-skill` — Scaffolding of a new skill repo

For the full destination taxonomy and routing heuristics, see retro-skill/references/destination-taxonomy.md.

Rule 1: Patches target source repos, never local cache

Local skill cache (~/.claude/plugins/cache/) is overwritten on plugin update. Edits there are lost. Always locate the source repository before patching.

Resolution order:

1. <skill-root>/.claude-plugin/plugin.json → repository field 2. <skill-root>/composer.json → support.source or homepage 3. <skill-root>/.git/config → remote.origin.url 4. Walk up parent directories from the resolved-symlink path looking for any of the above 5. Last resort: ask the user

If unresolvable: do NOT patch local cache. Either ask user or refuse.

Rule 2: Workspace preference order

For each skill-update target, select working directory in this order:

1. Existing worktree: ~/p/<repo-name>/main/ exists AND is a clean git worktree → use it. <repo-name> is the full GitHub repo name (e.g. skill-repo-skill, not skill-repo). 2. Existing flat checkout: ~/p/<repo-name>/ exists AND is a clean flat git checkout on main → use it. 3. Fresh clone: Otherwise clone into /tmp/retro-workspace/<repo-name>/.

Dirty checkouts: do NOT use. Fall back to /tmp. Always tell the user why.

Rule 3: Branch convention

feat/retro-<short-slug>

<short-slug> is kebab-case, derived from the friction title. Maximum 60 characters for the slug part (full branch ≤ 71 chars including feat/retro- prefix; comfortable on most terminals).

Examples:

• feat/retro-add-bun-trigger-keywords
• feat/retro-fix-yaml-tool-choice-for-data-tools

For new-skill: the new repo's first branch is main (initial scaffolding commit).

Rule 4: Commit conventions

• Format: Conventional Commits (<type>(<scope>): <summary>)
• Types: feat, fix, docs, refactor, chore
• No bot attribution. Never append "Generated with Claude Code" or "Co-Authored-By: Claude"
• Preserve signing. Never pass --no-gpg-sign or -c commit.gpgsign=false
• Preserve hooks. Never pass --no-verify
• DCO sign-off. All commits include Signed-off-by: <name> <email> trailer (use git commit -s or git rebase --signoff)
• Atomic. One logical change per commit

Commit message body should reference the friction:

feat(triggers): include bun in skill description keywords

Found via /retro session 2026-05-11: the assistant suggested npm
in 4 turns despite the project clearly using bun. SKILL.md description
didn't include 'bun' as a trigger.

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>

Rule 5: PR template

PRs created by retro-skill should use the named template retro.md:

gh pr create --template retro.md ...
# or via URL query when opening manually:
# https://github.com/<org>/<repo>/compare/main...<branch>?template=retro.md

This invokes .github/PULL_REQUEST_TEMPLATE/retro.md (not the repo's default template, if any). The retro template has:

• ## Summary
• ## Came from (session date, finding signal ID)
• ## Change (concrete diff scope)
• ## Target area (skills/<name>/SKILL.md / references/ / scripts/ / templates/ / checkpoints.yaml / evals/evals.json)
• ## Learning source (checkboxes: from /retro, reusable, scoped, eval included)
• ## Test plan (verification steps)

Rule 6: Target area mapping

Paths are relative to the skill's own subdirectory in the repo (this repo's convention: skills/<skill-name>/..., not repo-root).

Each skill-update PR should touch one primary area; multi-area is allowed when cohesive (e.g. SKILL.md update + corresponding eval).

Multi-area PRs split unrelated concerns into separate PRs.

Rule 7: Eval format (skill-repo convention)

This repo's eval format is a single `evals/evals.json` file containing an array of objects. Each object has at minimum:

{
  "name": "<scenario-name>",
  "prompt": "<what to ask the agent>",
  "assertions": [
    { "type": "content", "pattern": "<regex>" },
    { "type": "tool_use", "tool": "<ToolName>", "pattern": "<regex>" }
  ]
}

Validation: bash skills/skill-repo/scripts/validate-evals.sh.

When a skill-update PR changes behavior expectations, append a new eval object to the existing `evals/evals.json` array in the target skill's directory. Do NOT emit evals/*.md files — they will be rejected by the validator.

Other skill repos may use different eval conventions; consult each target's evals/ directory before submitting.

Rule 8: Per-private-repo confirmation

Before pushing to a private host (git.netresearch.de, gitlab.com/<private-org>, etc.), prompt the user. Decision is remembered per (session, repo-url) for the duration of the active retro-skill session; not persisted across sessions.

Rule 9: New-skill scaffolding

For new-skill destination, use the templates in skills/skill-repo/templates/:

• composer.json.template (with type: ai-agent-skill, split licensing in SPDX)
• package.json.template (for npm-distributable variants)
• LICENSE-MIT.template, LICENSE-CC-BY-SA-4.0.template
• README.md.template
• release.yml.template (GitHub Actions release workflow)
• validate.yml.template (CI caller for the reusable skill-validation workflow — without it the SKILL.md word cap, plugin.json schema, and markdown/yaml/action lints run only in local pre-commit, never in CI)
• pr-quality.yml.template (PR validation)
• auto-merge-deps.yml.template (Dependabot/Renovate auto-merge)
• pre-commit.template

Required files in the new repo:

• .claude-plugin/plugin.json (Claude marketplace manifest)
• composer.json (from template)
• skills/<name>/SKILL.md (skill definition)
• LICENSE-MIT, LICENSE-CC-BY-SA-4.0 (from templates)
• README.md (from template)
• AGENTS.md (agent-harness convention)
• .gitignore
• One initial skills/<name>/references/*.md covering the friction pattern
• One initial entry in skills/<name>/evals/evals.json covering the friction (TDD)
• Optionally skills/<name>/checkpoints.yaml (start with structural checkpoints)
• .github/workflows/release.yml (from template)
• .github/workflows/validate.yml (from template — required so skill validation runs in CI, not just pre-commit)

Run bash skills/skill-repo/scripts/validate-skill.sh <new-repo-path> to confirm the scaffold passes structural validation.

Marketplace listing is a separate manual step (out of scope for this contract).

See also

• retro-skill destination-taxonomy — Six destinations
• retro-skill patch-workflow — Workflow on the retro-skill side
• retro-skill eval-integration — How retro reads evals when proposing skill-update
• skills/skill-repo/templates/ — Scaffolding templates
• skills/skill-repo/scripts/validate-evals.sh — Eval validator
• skills/skill-repo/scripts/validate-skill.sh — Structure validator
• User memory: feedback_preserve-commit-signing, feedback_merge-strategy, feedback_no-version-bumps-in-feature-prs

README structure for Netresearch skill repositories

Human-facing documentation for a skill repo. Marketplace pages may summarize this content but must not become the only place where these facts exist.

Boilerplate generator: `../templates/README.md.template` — align templates with the headings below when updating scaffolding.

---

First screen (above-the-fold)

Without long scrolling, the reader must see answers to:

1. What problem does this skill solve? 2. When should it be used? 3. What does it produce? 4. What inputs or project context does it need? 5. How do I install it or find it in the marketplace?

---

Required Markdown sections (English)

Use exact level-2 headings so agents can grep them:

• ## What this skill solves
• ## Use when
• ## Expected outputs
• ## Context requirements
• ## Example prompts — minimum three fenced or bulleted realistic prompts (distinct scenarios).
• ## Related skills — slugs/URLs or explicit none (justified: …).
• ## Installation — must include Netresearch marketplace path (/plugin marketplace add netresearch/claude-code-marketplace) or pointer to org-standard install doc.
• ## Contributing
• ## License

Optional (skills that ship a `commands/` dir): ## Commands — a table or list enumerating every slash-command and each of its modes / sub-commands / flags. When you add or rename a command or a mode, update this list in the same change — the implementation, its reference docs, and the README/AGENTS menus drift apart otherwise (a mode added everywhere except the README menu is a common, user-visible miss). validate-skill.sh warns when a command's /<name> (from commands/<name>.md) is not mentioned in the README, but it cannot see mode-level drift — that part is on the author.

Optional: ## German summary — short paragraph if DACH/TYPO3/Oro/agency audience; technical detail may remain English. The scaffold `../templates/README.md.template` ships this as a commented block after ## License — uncomment when needed.

---

Voice: present tense, never narrate change

Reference docs (README, SKILL.md, reference files, module headers) describe what the skill is and how to use it, in plain present tense — as if it had always been this way. They must not describe the skill by what it is not or how it changed.

• Banned framing: "no longer", "instead of", "reframed", "previously", "used to", "X derives from Y / downstream … not its source", "it is not a router/wrapper/…". This is the curse of knowledge as negative / apophatic documentation — it only parses for a reader who knew a prior design.
• Before the first release there is no audience for change. Nobody ran a prior public version, so any before/after framing is noise and actively misleads (readers hunt for a "router" that never existed). The same holds for unreleased, in-between edits: the diff is the commit; the README must not know a change happened.
• History lives only in `CHANGELOG` / `UPGRADING` / release notes / ADRs / the commit log — those have a reader (someone upgrading from a version they used) who needs the contrast. The README and SKILL.md never do.
• A deprecation notice ("X is deprecated, use Y") is the one legitimate non-history contrast and belongs in the changelog/upgrade doc, not the "what this is" sections.

---

Cross-checks (machine-friendly)

---

Alignment with other files

• Discovery YAML (optional): `skill-discovery-metadata.md` — keep summaries consistent with README sections.
• `agents/openai.yaml`: short end-user description; must not contradict README summaries.
• GitHub: see `repository-quality-rules.md` for description/topic rules.

Release Discipline

Every step that caused the "30 failed plugin releases" incident, codified as rules.

Canonical Order: Bump PR Merged → Tag Pushed

Tag a version only after the version-bump PR is merged to the default branch. Tagging first causes the Release workflow to run against the old code, fail CI, and produce an immutable GitHub release locked to a bad tag.

WRONG: git tag -s v1.2.4 → git push → open bump PR
RIGHT: open bump PR → merge → pull main → git tag -s v1.2.4 → git push

Pre-Release Version-Parity Check

Before pushing any tag, all version identifiers must match. This is the single check that would have prevented the 30-repo release failure.

Use the shipped script scripts/check-version-parity.sh (in this repo under skills/skill-repo/scripts/check-version-parity.sh):

# No arguments — compare plugin.json against SKILL.md metadata.version
skills/skill-repo/scripts/check-version-parity.sh

# With tag argument — also require plugin.json.version == tag (v prefix optional)
skills/skill-repo/scripts/check-version-parity.sh v1.2.4

What it checks:

• .claude-plugin/plugin.json has a .version field — exits with an error if missing.
• composer.json does not have a .version field — composer versions come from the git tag via the Release workflow, so a hard-coded version drifts silently.
• If a tag argument is provided, plugin.json.version equals that tag with the v prefix stripped.
• Every skills/*/SKILL.md that declares metadata.version in frontmatter matches plugin.json.version.

If called without an argument and all parity passes, the script prints an advisory suggesting the next tag call. Run before every git push origin vX.Y.Z.

Cache Safety: Never Edit the Installed Copy

Installed skills and plugins live under ~/.claude/ (or wherever the marketplace resolves them). Editing these paths directly is always wrong — the next /plugin update or marketplace sync will silently overwrite your changes, taking any local fixes with it.

Paths that are off-limits for edits

• ~/.claude/skills/**
• ~/.claude/plugins/cache/**
• ~/.claude/plugins/marketplaces/**
• Anything inside a .bare/ directory (git bare clone; worktree source)

Pre-edit check

Before every Write or Edit in skill-repo workflows:

pwd_real=$(realpath .)
case "$pwd_real" in
  */.claude/skills/*|*/.claude/plugins/*|*/.bare/*)
    echo "REFUSING to edit installed/cache path: $pwd_real"
    echo "Navigate to the source worktree first."
    exit 1
    ;;
esac

Recovery when edits landed in the wrong place

1. Stop. Do not run /plugin update or composer update — they may wipe your edits. 2. diff -r ~/.claude/skills/<name>/ ~/projects/<name>-skill/main/skills/<name>/ to see what drifted. 3. Copy the legitimate changes into the source worktree. 4. Commit from the worktree; never from the cache.

Multi-Skill-Repo Release Dry-Run

When releasing >3 skill repos in one sweep, produce this manifest and wait for user approval before executing:

Skill-Repo Release Plan (2026-04-18)

| Repo                        | Current | Target  | Change type | Notes                  |
|-----------------------------|---------|---------|-------------|------------------------|
| netresearch/git-workflow    | 1.9.0   | 1.10.0  | minor       | adds critical-rules    |
| netresearch/github-project  | 2.10.0  | 2.11.0  | minor       | multi-repo-operations  |
| netresearch/skill-repo      | 1.18.0  | 1.19.0  | minor       | release-discipline ref |

Preconditions (verified per repo):
  [✓] default branch CI green
  [✓] no pending version-bump PR
  [✓] version-parity check passes
  [✓] working tree clean

Execution order per repo:
  1. Create version-bump PR on feat/release-vX.Y.Z branch
  2. Wait for CI green and approval
  3. Merge via merge-commit (respects atomic-commit policy)
  4. Pull main; run check-version-parity.sh vX.Y.Z
  5. Create signed tag vX.Y.Z
  6. Push tag
  7. Monitor Release workflow to green
  8. Halt all further releases if this one fails — produce rollback

Reply "go" to proceed, or name repos to skip.

Immutable-Release Caveat

Deleted GitHub releases do NOT free the tag for reuse. Once a release is published and deleted, that tag string is permanently locked as a deleted release — a new release with the same tag will fail. See git-workflow-skill → references/github-releases.md. Therefore: get it right the first time. The version-parity check above is what "right the first time" means in practice.

Tag Signing (Mandatory)

git tag -s vX.Y.Z -m "vX.Y.Z"         # -s: sign with GPG/SSH
git push origin vX.Y.Z                # signed tag reaches the remote

Never git tag vX.Y.Z (unsigned). Repos with protected tag rulesets will reject unsigned tags.

No --latest Drift for Non-Default Branches

When releasing from a non-default branch (e.g. a v1.x maintenance line while v2.x is default), pass --latest=false to avoid stealing the "Latest" badge by timestamp:

gh release create v1.5.12 --latest=false --title "v1.5.12" --notes-file CHANGELOG-v1.5.12.md

GitHub marks releases "Latest" by creation timestamp, not semver. A v1.5.12 created after v2.0.0 will become "Latest" without this flag — wrong, misleading, and often noticed only by downstream consumers.

Supply-Chain Attestation

Every release ships with provenance-attested archives and a Cosign-signed SHA256SUMS.txt that binds those archives by digest. Only the checksum file is Cosign-signed; the .zip/.tar.gz archives are integrity-protected through it — verifying the signature on SHA256SUMS.txt and then running sha256sum --check against the downloaded archive proves the archive was produced by this workflow.

All of this happens in the SAME job that publishes the GitHub Release, BEFORE the assets are made public — there is no window where unsigned or unattested artifacts are downloadable. The flow, in order:

1. Build *.zip and *.tar.gz archives. 2. Generate SHA256SUMS.txt over them. 3. Cosign keyless sign-blob the SHA256SUMS.txt → produces SHA256SUMS.txt.sigstore.json (Sigstore bundle format: cert + signature + Rekor inclusion proof in a single self-contained JSON; cosign v3+ default). The .sigstore.json extension is chosen so OSSF Scorecard's signed-releases probe recognises the signature — the content is identical to cosign's --bundle default output. 4. `actions/attest-build-provenance` generates a SLSA build-provenance attestation for the archives + checksums file → published to GitHub's attestation API. 5. `softprops/action-gh-release` publishes the GitHub Release with all assets attached at once.

Callers must grant three permissions on the calling job:

# .github/workflows/release.yml in the consuming repo
jobs:
  release:
    uses: netresearch/skill-repo-skill/.github/workflows/release.yml@main
    permissions:
      contents: write          # release upload
      id-token: write          # OIDC for sigstore (Cosign + attest-build-provenance)
      attestations: write      # GitHub native attestation API

If any of those scopes is missing the job fails fast with Resource not accessible by integration; contents: write alone is not enough.

Verify a downloaded release archive

Both commands below pin verification to the specific repository that's expected to have produced the release. --owner netresearch and https://github.com/netresearch/.* are tempting shortcuts but match every workflow run in the org — meaning a compromised or unrelated netresearch repo could mint a valid-looking attestation against an artefact that was never released from this repo. Always pin to the named repo.

# SLSA build provenance (GitHub-native attestation API)
# Substitute <repo-name> with the actual skill repo, e.g. matrix-skill.
# Archive name patterns: <skill>-skill-vX.Y.Z.zip and <plugin>-plugin-vX.Y.Z.zip.
gh attestation verify <skill-name>-skill-vX.Y.Z.zip --repo netresearch/<repo-name>

# Cosign sign-blob signature on the checksums (no GitHub API needed).
# The cert SAN reflects the SIGNER, which is the shared reusable release
# workflow (`netresearch/skill-repo-skill`), NOT the consuming repo. Pin the
# regex to skill-repo-skill, not the consumer. (`gh attestation verify` above
# walks the chain automatically; cosign's verifier doesn't.) The org-wide form
# `https://github.com/netresearch/.*` would accept signatures from any repo,
# branch, or workflow in the org — too loose for supply-chain verification.
cosign verify-blob \
  --bundle SHA256SUMS.txt.sigstore.json \
  --certificate-identity-regexp "^https://github\.com/netresearch/skill-repo-skill/\.github/workflows/release\.yml@" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS.txt

# Then verify the archive matches the (now-signed) checksum
sha256sum --check SHA256SUMS.txt

If verification fails:

• gh attestation verify returns error: no attestations found when --repo is wrong (or when the release predates this workflow).
• cosign verify-blob returns error: certificate identity does not match when the regex is wrong, or bundle verification failed when .sigstore.json doesn't correspond to the file.

Why one atomic job

Splitting attestation into a separate needs: release job (the original design here) creates a race: the GitHub Release publishes BEFORE the attestation exists, so anyone downloading in that window gets unsigned, un-attested artifacts. Folding everything into the same job before the upload eliminates the window — either the whole bundle (archives + signature + provenance) ships, or nothing does.

Same pattern as netresearch/.github/.github/workflows/golib-create-release.yml and netresearch/typo3-ci-workflows/.github/workflows/release.yml. No reason for skill repos to diverge.

The previously-documented with: attest: true opt-in is gone; the input is still declared as DEPRECATED — ignored so any caller that still passes it doesn't error syntactically, but every release now gets provenance unconditionally. Drop the with: block if attest was its only entry (also true for bump).

Repository Quality Rules (skill repositories)

Prüfbare Regeln für einzelne Skill-Repositories (netresearch/*-skill). Nicht für das Marketplace-Repository — Discovery-Katalog- und SEO-Governance für den Hub liegen in `netresearch/claude-code-marketplace` (AGENTS.md dort).

---

Lizenz (Netresearch Split-Modell)

• PASS, wenn LICENSE-MIT und LICENSE-CC-BY-SA-4.0 vorhanden sind und keine bare LICENSE-Datei existiert (siehe validate-skill.sh / Checkpoints).
• PASS für „LICENSE oder LICENSE.md“-Anforderungen außerhalb Netresearch: Split-Lizenz gilt als erfüllte Lizenzpflicht; einzelne LICENSE-Datei ist hier FAIL, wenn sie das Split-Modell ersetzt.

---

Mindestbestandteile eines Skill-Repos

Jedes Repo muss die folgenden Elemente enthalten oder eine explizite Begründung in README.md unter z. B. ## Repository extras (warum ein Pflichtobjekt fehlt).

---

Pflicht für README-Oberfläche

Siehe `readme-template.md` für die exakten Überschriften und `skill-discovery-metadata.md` für YAML-Zusatzfelder außerhalb von SKILL.md.

---

SKILL.md vs. Discovery

• `SKILL.md`: Laufzeitverhalten, Trigger, Arbeitsablauf — siehe `skill-quality.md`.
• Discovery / SEO / Marketplace-Felder: README, agents/openai.yaml, optionale Metadatei(en), GitHub Description/Topics — nicht als zusätzliche YAML-Schlüssel im SKILL.md-Frontmatter für Katalogzwecke.

Frontmatter (technische Grenze)

• Erforderlich: name, description (mit Präfix Use when…).
• Verboten für Discovery: eigene Schlüssel wie slug, tags, category, keywords, seo_* im Frontmatter.
• Optional (Agent Skills / Validator): license, compatibility, metadata, allowed-tools — nur wenn technisch nötig; keine Marketing-/SEO-Felder dort.

---

Related Skills (Repo-Ebene)

• Im README oder in Discovery-YAML als Slugs oder volle URLs angeben.
• PASS, wenn mindestens ein Eintrag oder die Zeile Related skills: none (justified — …) mit Grund vorhanden ist.
• FAIL, wenn beliebige Links nur für SEO gesetzt sind (nicht fachlich nachvollziehbar).

---

Marketplace-Sync (Quelle bleibt Repo)

Bei Änderungen an Discovery-Inhalten: siehe `marketplace-integration.md`. Agents müssen am Ende einer Änderung prüfen, ob Marketplace-Felder aktualisiert werden müssen (oder Override dokumentiert ist).

---

GitHub Repository SEO

Repository Description

• PASS: String length ≤ 160 characters (count before save).
• PASS: Mentions concrete technology (e.g. TYPO3, OroCommerce, Docker) or a named task domain (e.g. “extension PHPUnit matrix”, “Vite sitepackage build”).
• FAIL: Generic phrases such as “Useful AI skill for developers”, “ultimate automation assistant”.
• PASS: Understandable without opening README.md.

Good: Agent skill for TYPO3 Vite setup, SCSS architecture and frontend asset integration. Bad: Useful AI skill for developers.

GitHub Topics

• PASS: Includes `agent-skill`.
• PASS: At least one stack tag (typo3, php, docker, …) or domain tag (testing, security, frontend, …) matching the skill.
• FAIL: Irrelevant trending tags just for visibility (keyword stuffing).
• Document proposed topics in README under ## Repository extras if maintainers cannot edit Topics immediately.

---

GitHub Pages policy

The marketplace is the canonical public discovery and storytelling layer for all Netresearch Agent Skills. Repository Pages are secondary, skill-specific documentation surfaces.

Default: Pages disabled

Skill repositories must not enable GitHub Pages by default.

• PASS: gh api repos/netresearch/<repo>/pages returns HTTP 404 (Pages disabled).
• FAIL: Pages is enabled without satisfying the criteria below.

When Pages is appropriate

Enable GitHub Pages only when the repository contains standalone public material that is too large, too visual, too navigational, or too strategically important to live well in README.md. At least one of the following must be true:

• the documentation requires multiple pages,
• the skill has a gallery of examples, reports, dashboards, screenshots or demos,
• the skill publishes generated reference documentation,
• the skill provides versioned documentation,
• the skill is a public reference implementation,
• the skill explains a reusable methodology or assessment model,
• the skill has a specific SEO target that the marketplace landing cannot cover without becoming too broad.

When Pages is NOT appropriate

Do not enable Pages if the site would only duplicate:

• the README,
• the marketplace detail page (https://github.com/netresearch/claude-code-marketplace#<slug> or the future landing),
• installation instructions,
• SKILL.md,
• the basic example prompts.

Mandatory artefacts when Pages is enabled

If Pages is enabled, the repository must include:

• a short justification block in README.md (which criterion above is satisfied),
• a documented canonical URL pointing at the Pages site,
• a clear source path (default: docs/),
• documented build and deployment commands (make docs, npm run docs, or equivalent — referenced from the README),
• link-checking or equivalent validation in CI,
• a note explaining which content belongs on Pages vs. README vs. marketplace.

Mirroring rule

Skill-specific metadata originates in the skill repository (metadata/discovery.yaml, README sections, agents/openai.yaml, GitHub settings). The marketplace consumes it. Do not duplicate the same metadata across README, Pages site and marketplace landing — pick one canonical surface per fact and link from the others.

Reviewer-Reply Boilerplate

Canonical responses to recurring reviewer comments on Netresearch skill PRs (Copilot, Gemini Code Assist, peer review). Lift the fenced block verbatim or paraphrase to context. Each entry includes the criteria for whether to accept or decline.

These were extracted from review patterns across 14+ skill PRs. Use them to keep responses consistent and to avoid re-litigating settled architectural decisions on every new PR.

1. "Set private: true"

Verdict: Accept — already the template default.

Criteria: Skill packages distributed via github:org/repo (not the npm registry) must set "private": true to guard against accidental npm publish of the placeholder 0.0.0-source version. The current package.json.template bakes this in. If a reviewer flags it on a fresh PR, the package was scaffolded from an outdated template — accept the suggestion and add it.

Accepted. Adding `"private": true` — current scaffolding template (`skills/skill-repo/templates/package.json.template` in `netresearch/skill-repo-skill`) bakes this in to guard against accidental publish of the `0.0.0-source` placeholder. This PR was scaffolded before the template was updated.

2. "Pin github:org/repo#vX.Y.Z in install instructions"

Verdict: Decline as primary advice. Document #vX.Y.Z as an opt-in for users who want reproducibility.

Criteria: These skills are markdown content (procedural knowledge), not executable code where pinning protects against breakage. Consumers want skill-content updates by default. Pinning is an advanced opt-in.

Declined as primary advice. The default `github:netresearch/{repo-name}` form intentionally tracks the default branch so consumers receive skill-content updates — these skills are markdown content (procedural knowledge), not executable code where breakage matters. Pinning is an advanced use-case, not a default. Consumers can append `#vX.Y.Z` themselves for reproducibility (`github:netresearch/{repo-name}#v1.2.3`); we don't surface that in the README to keep the install path simple.

(Reference: this is the response we used on skill-repo-skill PR #82.)

3. "Drop .claude-plugin/ (or commands/, outputStyles/, AGENTS.md) from files"

Verdict: Decline (won't-fix). This is the dual-distribution invariant.

Criteria: Netresearch skill packages are dual-distributed — the same package serves both the Claude Code marketplace install path AND the npm install path. Plugin metadata, slash commands, output styles, and AGENTS.md are part of the skill's installable surface, not internal repo configuration. Excluding them from the npm tarball delivers a partial skill to npm consumers.

Declining. Netresearch skill packages are *dual-distributed* — the same tarball feeds both the Claude Code marketplace install path AND the npm install path. Plugin metadata (`.claude-plugin/plugin.json`), slash commands (`commands/`), output styles (`outputStyles/`), and the canonical `AGENTS.md` rules file are part of the skill's installable surface, not internal repo configuration.

Excluding them from the npm tarball would deliver a partial skill to npm consumers — the same partial-install problem documented in [github-release-skill PR #19](https://github.com/netresearch/github-release-skill/pull/19)'s `> **Limitation:**` callout. The current `@netresearch/agent-skill-coordinator` (v0.1.x) `node_modules` scanner can't load plugin-mechanism features; those need Claude Code's plugin loader. Shipping these directories preserves the option to switch install methods without re-installing.

(Reference: lifted from skill-repo-skill PR #83.)

4. "Top-level scripts/ shouldn't ship"

Verdict: Accept if scripts/ is repo-maintenance only. Decline if installed code reads from $ROOT/scripts/ at runtime.

Criteria: This is the opposite call from #3. Top-level scripts/ is not part of the dual-distribution surface unless the skill's runtime explicitly reads from it. To tell them apart:

• Repo-maintenance (DO accept the suggestion, remove from files): scripts that only run in CI or by repo maintainers — verify-harness.sh, generate-dashboard.sh, run-ab-evals.sh, lint runners, release helpers. Look for invocation only in .github/workflows/ or Makefile / package.json scripts.
• Runtime (DO decline the suggestion, keep in files): scripts the installed skill executes, typically referenced from skills/<name>/SKILL.md or skills/<name>/scripts/*.sh via $ROOT/scripts/... or ../scripts/....

Quick check: grep -r '\$ROOT/scripts\|\.\./scripts' skills/. If empty, it's repo-maintenance.

Accepted. `scripts/` at the repo root only contains `verify-harness.sh` (repo-maintenance, run via `.github/workflows/`). The installed skill code does not read from `$ROOT/scripts/` at runtime — runtime scripts live under `skills/<name>/scripts/` (already covered by the `skills/<name>/` entry). Removed from `files`. The npm-pack-smoke CI job will keep this honest going forward.

If declining (runtime usage):

Declining. Top-level `scripts/` is consumed at runtime — `skills/<name>/SKILL.md` references `$ROOT/scripts/<file>.sh` for [specific feature]. Removing it from `files` would break npm consumers. The npm-pack-smoke CI job asserts this dir is present.

5. "AGENTS.md shouldn't ship"

Verdict: Decline (won't-fix). Same dual-distribution invariant as #3.

Criteria: AGENTS.md is the canonical agent rules entry point for the skill repo. npm consumers expect the same rules file marketplace consumers see — without it, agents reading the package don't get the harness contract.

Declining. `AGENTS.md` is the canonical agent rules entry point for the skill — npm consumers must receive the same rules file that marketplace consumers do, otherwise agents reading the installed package miss the harness contract documented there. This is part of the dual-distribution surface (see [skill-repo-skill PR #83](https://github.com/netresearch/skill-repo-skill/pull/83)).

See Also

• installation-methods.md — Method 4 (npm) for the full files-allowlist rationale.
• release-discipline.md — version-parity check, multi-repo dry-run.
• skill-repo-skill PR #83 — original dual-distribution decision record.

Skill Discovery Metadata (repository scope)

Defines skill-repo-local discovery and classification data. Does not replace the marketplace catalog — the marketplace aggregates and may normalize display. Governance for marketplace listings is in `netresearch/claude-code-marketplace`/`AGENTS.md`.

---

Where metadata lives

Rule: SKILL.md describes how the agent behaves. Marketplace-oriented fields belong in README or a separate metadata file consumed by humans/tools — not stuffed into frontmatter beyond name/description (and optional technical keys above).

---

Recommended discovery YAML (optional file)

Place at repo root or under metadata/ — not inside SKILL.md. Example schema:

slug: typo3-vite
display_name: TYPO3 Vite Frontend Pipeline
summary:
  en: >
    Configures Vite for TYPO3 v13+ with vite-asset-collector, SCSS entrypoints, and CSP-safe asset URLs.
  de: >
    Richtet Vite für TYPO3 v13+ mit vite-asset-collector, SCSS-Entrypoints und CSP-tauglichen Asset-URLs ein.
category: typo3-frontend
tags:
  - vite
  - typo3
  - scss
  - frontend
use_cases:
  - Bootstrap a Vite pipeline for a TYPO3 sitepackage.
  - Split CSS/JS entrypoints per content element.
expected_outputs:
  - Vite config and npm scripts aligned with vite-asset-collector.
  - Documented build and deployment steps for frontend assets.
context_requirements:
  - TYPO3 v13+ sitepackage or extension with asset collector available.
  - Node.js LTS matching project policy.
action_level: modifies_files
risk_level: medium
related_skills:
  - typo3-frontend-patterns
  - dxp-frontend
example_prompts:
  - "Add Vite 7 to our TYPO3 13 sitepackage with SCSS partials per content element."
  - "Wire vite-asset-collector entrypoints for tt_content templates."
primary_keywords:
  - vite
  - typo3
  - sitepackage

Fields:

• `slug`: stable id; usually matches plugin/skill name.
• `display_name`: public title (may differ from name in SKILL.md).
• `summary.en` / `summary.de`: one short paragraph each; de optional unless DACH/TYPO3/Oro focus. `summary.en` should be ≤ 300 chars (snippet-friendly target; the marketplace enforces a hard cap of 500).
• `category`: one of the canonical marketplace categories — development, devops, security, design, workflow, productivity. Keep this in sync with the marketplace AGENTS.md canonical list; do not invent ad-hoc values.
• `tags` / `use_cases`: for README tables and marketplace sync.
• `expected_outputs` / `context_requirements`: must mirror README sections (single source: generate README from this file or maintain parity explicitly).
• `related_skills`: slugs or full GitHub URLs; see `repository-quality-rules.md`. Entries that don't yet exist in the catalog can be tagged (planned) or (external) — never invent fake links for SEO.
• `example_prompts`: align with README Example prompts (≥3 in README per checklist).
• `primary_keywords`: align with GitHub Topics + first sentence of summaries.

---

Action level

Risk level

PASS rule: every skill repo should state action_level and risk_level in discovery YAML or in README table „Classification“ with the same labels.

---

Sync with marketplace

When this metadata changes, open or update the corresponding marketplace entry per `marketplace-integration.md`. Do not silently diverge.

SKILL.md Quality Rules — Detail and Examples

Detailed guidance backing the summary in `SKILL.md` (§ SKILL.md Quality Rules).

Why these rules exist

Claude Code skills have two distinct context costs:

• Listing cost (per turn): Only name, description, and optional when_to_use from each skill's frontmatter enter context on every assistant turn — whether the skill is invoked or not. Per-skill cap: 1,536 chars (skillListingMaxDescChars). Total listing cap: skillListingBudgetFraction × context_window (default 0.01).
• Body cost (per invocation): The full SKILL.md body loads when the skill is invoked, and persists for the rest of the session. Reference files (references/*.md) are not auto-loaded — the model only reads files it sees referenced.

Description bytes are the always-on tax; body bytes are the on-demand tax. References are free unless the model knows they exist and decides to read them.

Description rules

Caps

• Hard cap: 1,536 chars — Claude Code truncates above this regardless of budget.
• Target: 100–300 chars — fits comfortably in the listing, leaves headroom for other skills.
• Justify above ~500 chars — long descriptions are reasonable when they enumerate triggers (e.g., ticket-key prefixes, file-extension lists). Keep the structure tight.

Position matters

Truncation is position-based. Put your primary trigger first. The convention is Use when <trigger> as the opener.

Anti-patterns

Examples

Good:

description: "Use when reviewing your diff, writing a commit message, or asking what changed. Summarizes uncommitted changes and flags risky patterns."

Bad:

description: "A comprehensive solution for managing your repository state with advanced semantic understanding"

Body rules

Size

Body loads on invocation and persists for the rest of the session. The threshold goal is per-invocation token cost — every additional word in the body is paid every time the skill is invoked. Move what isn't strictly needed at decision time into references/ (lazy-loaded when SKILL.md instructs).

Word count translates to tokens at roughly 1.4× (English prose; code fences run higher). audit-skills.sh reports three tiers:

• INFO above 500 words (~700 tokens) — modest cost; skim for split candidates.
• WARN above 1,000 words (~1,400 tokens) — almost any body at this size has lookup content that could move to references.
• FAIL above 2,000 words (~2,800 tokens) — body is acting as a manual; split required.

These tiers are advisory across the wider skill ecosystem. This repo enforces a stricter 500-word hard cap on its own SKILL.md (via scripts/validate-skill.sh) — that is the per-skill house rule, not a universal claim. Treat the audit tiers as triage levels for any skill repo; treat the 500-word cap as policy for the canonical skill-repo template.

Empirical anchor: the Netresearch skill corpus (n=52) has p95 ≈ 994 words. WARN at 1,000 catches the actual outliers in our own work. Anthropic's longer skills (e.g., writing-skills at 3,193 words) FAIL under this rule — that's the honest signal: even shipped skills can have content moved out. We can't fix theirs; we hold ourselves to the rule.

• Bloat signals: body >3 KB, body >150 lines, single fenced code block >25 lines (long code examples are the primary lazy-load target).

When to split to references/

Move to references/<topic>.md when content is:

• Long examples (>20 lines)
• Configuration templates
• API/syntax tables
• Migration matrices
• Detailed checklists
• Repository directory trees (often the worst offenders)

Keep in SKILL.md body:

• High-level workflow
• The "what does this skill do" summary
• A reference catalog (see Pattern 2 below) when there are many topic-files
• One canonical quick example

Reference patterns

Every .md file in references/ must be discoverable to the model from SKILL.md. Three acceptable patterns:

Pattern 1: Direct cite

For form validation, see [`references/forms.md`](references/forms.md).
For multi-profile auth, see [`references/multi-profile.md`](references/multi-profile.md).

Best for ≤10 reference files. Each gets a one-line cite with the path. The model sees the path on invocation and reads on demand.

Pattern 2: Catalog-with-convention

## Reference Files (in `references/`, `.md` implied)

- **Frameworks** (`*-security`): react, vue, angular, nextjs, nuxt
- **Languages** (`*-security-features`): php, python, go, rust, javascript-typescript
- **Cloud** (`*-security`): aws, azure, gcp

Best for 10+ topic-grouped files. The model sees:

• The directory (references/)
• The filename suffix convention (-security, -security-features)
• The list of stems

It can resolve any combination on demand. The security-audit skill uses this pattern for ~60 reference files in ~12 lines of body content.

Pattern 3: List-and-pick

For language-specific guidance, list `references/` and read the file matching your stack.

Use sparingly — burns a tool call (the model has to enumerate the directory). Useful when there's no naming convention but the directory is small.

Anti-pattern: Hub-and-spoke

# DON'T DO THIS

In SKILL.md:
> See [references/index.md](references/index.md) for the catalog of references.

In references/index.md:
> - [forms.md](forms.md)
> - [auth.md](auth.md)

Multi-hop traversal isn't reliable. Anthropic's docs phrase the rule as "Reference supporting files from SKILL.md so Claude knows what each file contains" — direct visibility from SKILL.md is the model. The hub gets read but its leaves aren't deeply traversed. Anthropic's published skills use flat / catalog patterns, never hub-and-spoke.

Anti-pattern: Orphan refs

Files in references/ with no path to discovery from SKILL.md (no direct cite, no catalog mention, no list-and-pick instruction). The model never reads them. Either cite them or delete them — they consume disk and signal "stale" to readers without contributing to the skill's behavior.

Auditing

Run scripts/audit-skills.sh from the repo root. It scans SKILL.md files for:

• Description length violations (warn >500 chars, fail >1,536)
• Body length tiers (info >500 words, warn >1,000, fail >2,000)
• Long code fences (info >25 lines — primary lazy-load candidate)
• Orphan refs (files in references/ not reachable by any pattern)

Pattern 2 detection is heuristic: a reference file counts as P2 when its stem matches a convention stated in SKILL.md (filename suffix or topic-list pattern). Files outside any P1/P2/P3 path are reported as ORPHAN.

Sources

• Anthropic Claude Code docs on skills: <https://code.claude.com/docs/en/skills>
• Anthropic published skills: <https://github.com/anthropics/skills>
• Settings schema: skillListingBudgetFraction, skillListingMaxDescChars (Claude Code settings.json)

Validation checklist — skill repository changes

Agents must walk through this list before declaring a skill-repo task complete. Marketplace-only checks live in `netresearch/claude-code-marketplace`/`AGENTS.md` — do not merge those steps here.

README

• [ ] README.md contains all required sections listed in `readme-template.md`.
• [ ] Example prompts: ≥ 3 realistic prompts in ## Example prompts.
• [ ] Related skills: declared or none (justified: …).
• [ ] First screen answers: problem, when, outputs, context, installation — verifiable without scrolling past ~1 screen (approx. first 40 lines).

SKILL.md

• [ ] Frontmatter includes `name` and `description`; no discovery-only keys (slug, tags, category, keywords, …).
• [ ] Optional keys only if needed: license, compatibility, metadata, allowed-tools (per validator).
• [ ] description starts with Use when.
• [ ] Body describes triggers and use cases without duplicating full README marketing copy.

Agents / OpenAI

• [ ] agents/openai.yaml exists or README documents exception.
• [ ] File contains a short, user-understandable description of the skill (what/when).

Discovery metadata

• [ ] Optional metadata/discovery.yaml (or documented equivalent) matches README if used — see `skill-discovery-metadata.md`.
• [ ] `action_level` and `risk_level` present in discovery YAML or README classification table.

GitHub repository SEO

• [ ] Repository Description ≤ 160 characters, names concrete tech or use case — not generic “AI assistant”.
• [ ] Topics include agent-skill plus relevant tech/domain tags; no irrelevant stuffing.

GitHub Pages

• [ ] gh api repos/netresearch/<repo>/pages returns HTTP 404 (Pages disabled — the default).
• [ ] If Pages is enabled: the PR description names which repository-quality-rules.md Pages criterion is satisfied, and the README contains the mandatory artefacts (justification, canonical URL, source path, build/deploy commands, link-checking, content-split note).

Related skills

• [ ] Related skills list is honest (exists, planned, or external) — see `repository-quality-rules.md`.

Marketplace sync expectations

• [ ] README contains note or checkbox: when discovery fields change, marketplace entry must be updated or override documented (see `marketplace-integration.md`).

Links and automation

• [ ] All links in touched docs resolve (internal paths and GitHub URLs).
• [ ] bash skills/skill-repo/scripts/validate-skill.sh exits 0 from repo root.
• [ ] If repo has CI calling netresearch/skill-repo-skill/.github/workflows/validate.yml, PR checks are green.

Optional extended validation

• [ ] scripts/audit-skills.sh (if present in repo) reports no new orphan references/ files.