{
  "markdown": "# SVG153 Skills\n\n[![Skills Validation](https://github.com/svg153/skills/actions/workflows/validate.yml/badge.svg)](https://github.com/svg153/skills/actions/workflows/validate.yml)\n[![Catalog Validation](https://github.com/svg153/skills/actions/workflows/catalog-validate.yml/badge.svg)](https://github.com/svg153/skills/actions/workflows/catalog-validate.yml)\n[![Behavioral Eval Static Validation](https://github.com/svg153/skills/actions/workflows/eval-static.yml/badge.svg)](https://github.com/svg153/skills/actions/workflows/eval-static.yml)\n\nCross-agent catalog of reusable Agent Skills with provenance-aware lifecycle management, reproducible upstream synchronization, behavioral evals, and generated distribution surfaces.\n\n**Public catalog:** https://svg153.github.io/skills/.\n\n## Why this catalog exists\n\nAgent 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:\n\n- **provenance** — where a skill came from and which source is authoritative;\n- **lifecycle** — local, curated-upstream, or automatically mirrored ownership;\n- **distribution** — one canonical catalog rendered for several agent/plugin ecosystems;\n- **regression evidence** — deterministic checks plus Waza behavioral suites where useful;\n- **safe reuse** — imported content keeps its upstream authorship and license rather than being silently relicensed.\n\n## Install\n\nInspect or install with the cross-agent `skills` CLI:\n\n```bash\nnpx skills@latest add svg153/skills --list\nnpx skills@latest add svg153/skills --skill github-build-or-reuse\nnpx skills@latest add svg153/skills --skill social-publishing --agent codex --global\n```\n\nSelected entries can also be consumed as Microsoft APM packages. For example:\n\n```bash\napm install svg153/skills/skills/social-publishing --target agent-skills\napm install --frozen\napm audit\n```\n\n## One source of truth, multiple consumers\n\nCanonical catalog/package state lives in:\n\n```text\nskills/<name>/SKILL.md       portable runtime behavior\nskills/<name>/metadata.yaml  catalog provenance + lifecycle\nskills.sh.json               curated grouping/discovery\ndistribution.config.json     package identity + optional MCP composition/provenance\n```\n\nThe distribution architecture is **plugin-first, skill-canonical**:\n\n```text\nAgent Plugin package                 preferred installable capability boundary\n├── plugin.json\n├── skills/*/SKILL.md                canonical portable behavior\n├── mcp.json                         optional reusable MCP composition\n└── client-specific extensions       only when necessary\n\nExternal distribution/discovery\n├── skills.sh                         retained while it adds discovery/install reach\n└── host adapters                     generated compatibility surfaces, retired by parity\n```\n\nAgent 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.\n\nSee [ADR 0002](docs/adr/0002-plugin-first-distribution.md) and [distribution manifests](docs/distribution-manifests.md).\n\n```bash\npython scripts/generate-distribution.py\npython scripts/generate-distribution.py --check\n```\n\n## Optional MCP composition\n\nAgent Plugins 1.0 can package connections to **existing MCP servers** alongside skills; the MCP server does not need to be implemented in this repository.\n\n`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.\n\nThe 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.\n\nThis is deliberately a **package-level** concern: registering an individual skill does not silently inject an MCP into the whole catalog bundle.\n\nSee [docs/mcp-composition.md](docs/mcp-composition.md).\n\n## Capability plugins\n\nThe 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.\n\nThe first pilot is [`plugins/planning/`](plugins/planning/):\n\n```text\nplanning Agent Plugin\n├── planning skill\n├── backlog-management skill\n├── GitHub official MCP\n└── Atlassian Rovo MCP\n```\n\nIt keeps GitHub/Jira as the authoritative planning systems rather than creating another project-management store.\n\nCapability 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:\n\n```bash\ncopilot plugin marketplace add svg153/skills\ncopilot plugin marketplace browse svg153-skills\ncopilot plugin install planning@svg153-skills\n```\n\nCopilot 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.\n\nPackage 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:\n\n```bash\npython scripts/generate-capability-plugin.py \\\n  --config plugins/planning/distribution.config.json \\\n  --check\n\npython scripts/generate-distribution.py --check\n```\n\n## Lifecycle model\n\nEvery catalog entry has one explicit ownership mode:\n\n| Ownership | Metadata | Meaning |\n| --- | --- | --- |\n| `LOCAL` | `strategy: local`, disabled, `authoritative: local` | Authored and maintained here. |\n| `CURATED_UPSTREAM` | `strategy: manual`, disabled, `authoritative: local` | Upstream provenance retained, local adaptation authoritative. |\n| `MIRRORED_UPSTREAM` | `strategy: download`, enabled, `authoritative: upstream` | Stable upstream payload can replace the local mirror. |\n\n`origin_ref: latest-release` resolves only stable `vX.Y.Z` releases. It deliberately ignores prereleases and unpublished `main` changes.\n\nValidate lifecycle state with:\n\n```bash\npython scripts/validate-metadata-lifecycle.py\npython skills/skill-publish/scripts/metadata_repair.py check\n```\n\n## Add or register a skill\n\nUse `skill-publish` as the normal path instead of manually touching every catalog surface.\n\n1. Decide `LOCAL`, `MIRRORED_UPSTREAM`, or `CURATED_UPSTREAM`.\n2. Prepare the spec described in `skills/skill-publish/references/creation-contract.md`.\n3. Produce a zero-write plan:\n\n```bash\npython skills/skill-publish/scripts/catalog_skill.py plan --spec /path/to/spec.json\n```\n\n4. Review and approve the exact hash, then apply:\n\n```bash\npython skills/skill-publish/scripts/catalog_skill.py apply \\\n  --spec /path/to/spec.json \\\n  --approve <approval_hash>\n```\n\nThe 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.\n\nLegacy metadata can be normalized with the same approval boundary:\n\n```bash\npython skills/skill-publish/scripts/metadata_repair.py plan\npython skills/skill-publish/scripts/metadata_repair.py apply --approve <approval_hash>\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the manual/fallback contract.\n\n## Upstream synchronization\n\nAutomatic synchronization is intentionally generic: no per-skill sync workflows.\n\n```bash\n./scripts/sync-upstreams.sh --list\n./scripts/sync-upstreams.sh --all\n./scripts/sync-upstreams.sh --due\n./scripts/sync-upstream-skill.sh github-build-or-reuse\n./scripts/check-updates.sh\n```\n\n`.github/workflows/sync-upstream-skills.yml` runs daily; each `MIRRORED_UPSTREAM` entry's metadata controls whether it is due.\n\n## Behavioral evals\n\nCatalog-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.\n\nFor 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.\n\nSee [docs/evals.md](docs/evals.md) and [ADR 0001](docs/adr/0001-behavioral-skill-evaluations.md).\n\n## Public catalog\n\nThe GitHub Pages site is generated from canonical metadata, not maintained separately:\n\n```bash\npython scripts/generate-catalog.py --output /tmp/skills-catalog --base-path /skills\npython scripts/validate-catalog.py --site-dir /tmp/skills-catalog --base-path /skills\n```\n\nPublished at https://svg153.github.io/skills/.\n\n## Optional Hermes integration\n\nHermes is a local consumer, not part of portable catalog lifecycle logic. Its helper therefore lives under `integrations/hermes/`:\n\n```bash\n./integrations/hermes/sync-all.sh full\n```\n\nThis direction is separate from upstream synchronization:\n\n```text\nexternal upstream -> svg153/skills catalog -> local Hermes runtime\n```\n\n## External discovery\n\n`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.\n\nskills.sh is intentionally retained while it contributes practical discovery/install reach. It should not be removed merely because a portable `plugin.json` exists.\n\n## Contributing and project policy\n\nContributions are welcome through the repository issue forms and pull-request template. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the lifecycle/provenance model above.\n\n- [LICENSE](LICENSE) — MIT for repository-authored material, subject to more specific per-skill licenses.\n- [NOTICE.md](NOTICE.md) — license precedence and third-party provenance model.\n- [SECURITY.md](SECURITY.md) — private vulnerability reporting and security scope.\n- [GOVERNANCE.md](GOVERNANCE.md) — maintainer roles, decision model, and catalog invariants.\n\nRuntime 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.\n",
  "bytes": 10951,
  "sha": "99c5628b9723b3abe1eb354fc52117558b8401a21f6cbc7ed7a1b5e17d9c8b56",
  "repo_slug": "svg153/skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_svg153_skills_42962a28/readme"
}