SVG153 Skills

Skills Validation Catalog Validation Behavioral Eval Static Validation

Cross-agent catalog of reusable Agent Skills with provenance-aware lifecycle management, reproducible upstream synchronization, behavioral evals, and generated distribution surfaces.

Public catalog: https://svg153.github.io/skills/.

Why this catalog exists

Agent Skills are easy to copy and hard to govern once they come from multiple sources. This repository keeps portability without losing the information needed to operate a real catalog:

provenance — where a skill came from and which source is authoritative;
lifecycle — local, curated-upstream, or automatically mirrored ownership;
distribution — one canonical catalog rendered for several agent/plugin ecosystems;
regression evidence — deterministic checks plus Waza behavioral suites where useful;
safe reuse — imported content keeps its upstream authorship and license rather than being silently relicensed.

Install

Inspect or install with the cross-agent skills CLI:

npx skills@latest add svg153/skills --list
npx skills@latest add svg153/skills --skill github-build-or-reuse
npx skills@latest add svg153/skills --skill social-publishing --agent codex --global

Selected entries can also be consumed as Microsoft APM packages. For example:

apm install svg153/skills/skills/social-publishing --target agent-skills
apm install --frozen
apm audit

One source of truth, multiple consumers

Canonical catalog/package state lives in:

skills/<name>/SKILL.md       portable runtime behavior
skills/<name>/metadata.yaml  catalog provenance + lifecycle
skills.sh.json               curated grouping/discovery
distribution.config.json     package identity + optional MCP composition/provenance

The distribution architecture is plugin-first, skill-canonical:

Agent Plugin package                 preferred installable capability boundary
├── plugin.json
├── skills/*/SKILL.md                canonical portable behavior
├── mcp.json                         optional reusable MCP composition
└── client-specific extensions       only when necessary

External distribution/discovery
├── skills.sh                         retained while it adds discovery/install reach
└── host adapters                     generated compatibility surfaces, retired by parity

Agent Plugins can become the primary package without creating a second runtime source of truth. Host-specific manifests remain derived outputs and are candidates for retirement once native Agent Plugins install, discovery, runtime, update and governance parity is verified. skills.sh is deliberately evaluated separately and remains supported while it materially improves discovery.

See ADR 0002 and distribution manifests.

python scripts/generate-distribution.py
python scripts/generate-distribution.py --check

Optional MCP composition

Agent Plugins 1.0 can package connections to existing MCP servers alongside skills; the MCP server does not need to be implemented in this repository.

distribution.config.json may define package-level mcpServers. Each entry keeps portable connection config separate from catalog provenance. The generator emits root mcp.json only when at least one server is configured.

The policy supports streamable-http, intentional stdio, and legacy sse with justification. It rejects non-loopback cleartext HTTP, credential-bearing headers/environment variables, unsafe stdio commands/paths, and missing server provenance. OAuth, PATs and tokens remain client-managed rather than committed to package metadata.

This is deliberately a package-level concern: registering an individual skill does not silently inject an MCP into the whole catalog bundle.

See docs/mcp-composition.md.

Capability plugins

The repository can also host coherent Agent Plugins under plugins/ when a capability needs an independent install boundary, multiple related skills, or its own MCP/tool composition. These packages do not make their MCPs dependencies of the catalog-wide root bundle.

The first pilot is plugins/planning/:

planning Agent Plugin
├── planning skill
├── backlog-management skill
├── GitHub official MCP
└── Atlassian Rovo MCP

It keeps GitHub/Jira as the authoritative planning systems rather than creating another project-management store.

Capability packages are automatically included in the generated root marketplace.json. For GitHub Copilot CLI, use the marketplace path rather than a direct repo/subdirectory install:

copilot plugin marketplace add svg153/skills
copilot plugin marketplace browse svg153-skills
copilot plugin install planning@svg153-skills

Copilot CLI 1.0.83 warns that direct repo/URL/path plugin installs are deprecated and future releases will support marketplace installs only. CI therefore validates the marketplace-first path and requires both plugin-provided MCP servers to be discovered after installation.

Package manifests are deterministic outputs of each capability's local distribution.config.json plus its local skills/ tree, while the root marketplace is generated from the catalog plus discovered capability packages:

python scripts/generate-capability-plugin.py \
  --config plugins/planning/distribution.config.json \
  --check

python scripts/generate-distribution.py --check

Lifecycle model

Every catalog entry has one explicit ownership mode:

Ownership	Metadata	Meaning
`LOCAL`	`strategy: local`, disabled, `authoritative: local`	Authored and maintained here.
`CURATED_UPSTREAM`	`strategy: manual`, disabled, `authoritative: local`	Upstream provenance retained, local adaptation authoritative.
`MIRRORED_UPSTREAM`	`strategy: download`, enabled, `authoritative: upstream`	Stable upstream payload can replace the local mirror.

origin_ref: latest-release resolves only stable vX.Y.Z releases. It deliberately ignores prereleases and unpublished main changes.

Validate lifecycle state with:

python scripts/validate-metadata-lifecycle.py
python skills/skill-publish/scripts/metadata_repair.py check

Add or register a skill

Use skill-publish as the normal path instead of manually touching every catalog surface.

Decide LOCAL, MIRRORED_UPSTREAM, or CURATED_UPSTREAM.
Prepare the spec described in skills/skill-publish/references/creation-contract.md.
Produce a zero-write plan:

python skills/skill-publish/scripts/catalog_skill.py plan --spec /path/to/spec.json

Review and approve the exact hash, then apply:

python skills/skill-publish/scripts/catalog_skill.py apply \
  --spec /path/to/spec.json \
  --approve <approval_hash>

The workflow handles canonical metadata, optional APM/eval scaffolding, skills.sh registration, derived manifests, collision checks, and rollback on validation failure. Package-level MCP composition is governed separately by distribution.config.json; a skill-publish spec does not make an MCP mandatory for the whole bundle.

Legacy metadata can be normalized with the same approval boundary:

python skills/skill-publish/scripts/metadata_repair.py plan
python skills/skill-publish/scripts/metadata_repair.py apply --approve <approval_hash>

See CONTRIBUTING.md for the manual/fallback contract.

Upstream synchronization

Automatic synchronization is intentionally generic: no per-skill sync workflows.

./scripts/sync-upstreams.sh --list
./scripts/sync-upstreams.sh --all
./scripts/sync-upstreams.sh --due
./scripts/sync-upstream-skill.sh github-build-or-reuse
./scripts/check-updates.sh

.github/workflows/sync-upstream-skills.yml runs daily; each MIRRORED_UPSTREAM entry's metadata controls whether it is due.

Behavioral evals

Catalog-owned behavioral suites live under evals/<catalog-name>/ and use Waza. PR validation is deterministic and requires no model credential; trusted scheduled/manual runs execute model-backed suites and retain machine-readable evidence.

For upstream-authoritative mirrors, intrinsic behavior belongs upstream while catalog suites focus on routing/integration concerns and stay outside skills/<name>/ so synchronization cannot overwrite catalog policy or imply upstream authorship.

See docs/evals.md and ADR 0001.

Public catalog

The GitHub Pages site is generated from canonical metadata, not maintained separately:

python scripts/generate-catalog.py --output /tmp/skills-catalog --base-path /skills
python scripts/validate-catalog.py --site-dir /tmp/skills-catalog --base-path /skills

Published at https://svg153.github.io/skills/.

Optional Hermes integration

Hermes is a local consumer, not part of portable catalog lifecycle logic. Its helper therefore lives under integrations/hermes/:

./integrations/hermes/sync-all.sh full

This direction is separate from upstream synchronization:

external upstream -> svg153/skills catalog -> local Hermes runtime

External discovery

npx skills discovery and skills.sh search ingestion are separate concerns. CI runs npx skills with telemetry disabled and never generates artificial installs to influence ranking.

skills.sh is intentionally retained while it contributes practical discovery/install reach. It should not be removed merely because a portable plugin.json exists.

Contributing and project policy

Contributions are welcome through the repository issue forms and pull-request template. Start with CONTRIBUTING.md and the lifecycle/provenance model above.

LICENSE — MIT for repository-authored material, subject to more specific per-skill licenses.
NOTICE.md — license precedence and third-party provenance model.
SECURITY.md — private vulnerability reporting and security scope.
GOVERNANCE.md — maintainer roles, decision model, and catalog invariants.

Runtime behavior belongs in SKILL.md; catalog provenance/lifecycle belongs in metadata.yaml; package-level MCP composition belongs in distribution.config.json; generated distribution files remain derived outputs.