Agents Registry
The open-source source of truth for agents and multi-agent flows across supported install targets (GitHub Copilot, Cursor, Claude Code, and OpenAI Codex).
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
The open-source source of truth for agents and multi-agent flows across supported install targets (GitHub Copilot, Cursor, Claude Code, and OpenAI Codex).
Central open-source registry of AI agent configurations, developer workflows, skills, and runtime specifications. Compatible with CLI tools, IDE extension protocols, and MCP.
This repository defines deterministic, AI-readable specifications and stores registry packages.
Registry responsibilities:
packages/.specs/.This repository is intentionally data-first and specification-first. Runtime logic is out of scope for this initial baseline.
Use the pinned runtime to keep local development, agent tasks, and CI aligned.
24.18.0 (see .nvmrc and .node-version)12.0.1 (see packageManager in package.json)This repository prefers GitHub communication through gh CLI for issue and
pull request operations.
Verify availability and authentication:
gh --version
gh auth status
If gh auth status reports no login, run gh auth login.
nvm use
corepack enable npm
corepack prepare [email protected] --activate
npm ci
npm run env:check
npm 12 blocks dependency install scripts until they are explicitly approved.
This repository allowlists required scripts in package.json (allowScripts).
CI fails if npm ci leaves unreviewed scripts.
When adding or upgrading a dependency with lifecycle scripts:
npm install-scripts ls
npm install-scripts approve <name>@<version>
Then commit the updated allowScripts entry in package.json.
If you do not use nvm, install Node 24.18.0 manually and then run the
same Corepack and npm commands.
Common gh commands used in this workflow:
# inspect issue scope
gh issue view <number> --repo agents-repo/registry
# open a draft PR with template-aligned body content
gh pr create --repo agents-repo/registry \
--draft --title "..." \
--body-file <file>
Every PR targeting main MUST include a tracking reference in
## Related Issues: Closes #<issue-number> for standard tasks, or the
security-advisory format defined in the Workflow exceptions section of
.github/CONTRIBUTING.md when no public tracking issue exists. Package
submissions MAY omit a tracking issue; when no issue exists, describe the
package in ## Related Issues instead of Closes #. See Package Submission
Expectations. See
Required Workflow for the
canonical policy (branch → push → draft PR before implementation; tracking
issue recommended for most work).
Package contributors SHOULD fork the registry, work on the fork, and open a
pull request to upstream main. After the draft PR, the suggested authoring
path is full-package-creation-flow (already in the clone). See Submit a
package on agents-repo.org.
This repository commits IDE deployment mirrors so contributors get agent instructions on clone without manual install steps.
Regenerate mirrors after editing .cursor/rules/agents-registry.mdc:
npm run sync:ide-instructions
Do not edit generated .github/copilot-instructions.md, CLAUDE.md, or
AGENTS.md directly.
AI contributors: see docs/ai-onboarding.md for first-5-minutes commands, skill routing, and validation expectations.
For recurring ESLint/Sonar patterns and local duplication scans, see the
org AI static-analysis guide.
npm run dup:check (jscpd) runs in PR baseline CI (clone baseline gate) on registry
tooling (scripts/, tests/, specs/, .github/); the catalog tree packages/**
is excluded because package quality is enforced by the package:* scripts. Refresh
.jscpd-baseline.json with npm run dup:check:baseline after intentional deduplication.
Review-task commands (lint:sonar, dup:check, and related checks) are in
docs/ai-onboarding.md.
Install and refresh catalog packages with the agents-repo CLI.
After npm ci, use the npm scripts (CLI pinned in devDependencies):
npm exec agents-repo -- init --targets github-copilot claude-code cursor openai-codex
npm run agents:install # bulk sync from agents.json
npm run agents:update # refresh within semver ranges
npm run agents:verify # PR baseline parity when agents paths change
npm run agents:ci # full reinstall before changing locks or extracts
Commit agents.json, agents-lock.json, and extracted paths (.github/agents/,
.cursor/skills/, .claude/agents/, .agents/skills/). Do not hand-edit
extracted package files.
Dogfooded packages:
agents-repo/agents-repo-package-creation — all four IDE targetsmaiconfz/github-pr-review-triage — all four IDE targetsmaiconfz/github-interactive-issue-implementation-planner — all four IDE targetsSee .github/CONTRIBUTING.md for the full edit workflow.
MAJOR.MINOR.PATCH sourced from
https://semver.org.PATCH is the canonical term for backward-compatible bugfix releases.main (post-merge integration via pull request, not direct push)
run release validation checks. Platform merges may execute semantic-release
immediately; package merges do not (see Catalog release train below).agents-repo/registry. On forks they skip (the
workflow run still appears; jobs are skipped, not disabled). Sync main
from upstream to pick up the skip.workflow_dispatch remains available for operational checks on
agents-repo/registry.dry_run defaults to true; set dry_run=false only when intentionally
running a manual publish from main.v<MAJOR>.<MINOR>.<PATCH> format.The semantic version value remains <MAJOR>.<MINOR>.<PATCH>. The leading
v is only the Git tag naming convention used for release tags.
The release workflow uses Conventional Commit semantics. Custom release
rules in .releaserc.json map all feat(package) and fix(package)
commits—including ! and BREAKING CHANGE: footers—to no immediate
registry release. Platform breaking changes use commit-analyzer built-in
default rules when no custom rule matches:
type!: or BREAKING CHANGE: (without package scope) => MAJORfeat(package): and feat(package)!: => no immediate registry release
(catalog addition or new package version; batched daily)fix(package): and fix(package)!: => no immediate registry release
(package correction; batched daily)feat: with any other or no scope => MINOR (platform or tooling changes)fix:, perf:, and revert: with any scope except package => PATCHRegistry catalog Git tags (for v2.x consumers) are published by
.github/workflows/catalog-release.yml:
packages/ has unreleased
changes since the latest v* tag.workflow_dispatch on the same workflow.Package merges land on main immediately. v2.x pins may lag by up to ~24
hours until the next catalog release when packages/ changed. The
agents-repo CLI and agents.json refs
like v2.x resolve catalog snapshots from registry Git tags; versioned
/pkg/.../<package-version>/... paths on registry.agents-repo.org are
independent of the catalog tag cadence.
Registry Git tags (for example v2.0.1) version the catalog snapshot
consumed via refs like v2.x. Package versions/manifest.json latest values
version individual package compatibility. These layers are independent.
Package squash-merge titles classify package intent; catalog registry tags are
published on the daily catalog release train when packages/ has unreleased
changes. Express breaking package compatibility in the package's own semver
(for example 1.0.0 → 2.0.0). Registry MAJOR is reserved for platform,
tooling, or spec breaking commits without the package scope.
Commit types not listed above do not trigger an automated release.
Examples:
feat!: remove legacy manifest field => major bumpfeat: add release dashboard metadata => minor bumpfeat(release): add scoped rules => minor bumpfeat(package): add agents-repo/hello-agent => no immediate registry release
(catalog batched daily)feat(package)!: publish agents-repo/hello-agent 2.0.0 => no immediate
registry release (catalog batched daily)fix(package): correct hello-agent metadata => no immediate registry release
(catalog batched daily)fix: adjust lint config => patch bumpShared workspace editor defaults are managed in .vscode/settings.json.
Policy for shared versus personal settings is documented in
.vscode/README.md.
These defaults are designed to remain stable across Linux, macOS, and Windows, while lint and formatting rules stay defined by repository tooling.
The shared workspace indentation default is 2 spaces, and JSON/JSONC
indentation is enforced by npm run lint:sonar for repo files outside
packages/**/versions/**.
registry/
packages/
.keep
index.json
specs/
package-format.md
package-detail-schema.md
metadata-schema.md
manifest-schema.md
agent-format.md
flow-format.md
versioning-rules.md
index-schema.md
scripts/
lib/
... (modular helpers, validators, and build/create utilities)
package-validate.ts
package-build.ts
package-create.ts
package-validate-artifacts.ts
tests/
unit/
... (mirrors scripts/lib structure for unit tests)
integration/
... (multi-module integration scenarios)
e2e/
... (workflow-level end-to-end checks)
fixtures/
... (shared test inputs and snapshots)
helpers/
... (shared test utilities)
tsconfig.json
README.md
LICENSE
To create a new package, invoke full-package-creation-flow after the
draft pull request (see Package Development Workflow).
packages/agents-repo/hello-agent/README.md is a published example to read,
not the starting recipe.
See NAMESPACE_RULES.md and MIGRATION.md for namespaced package layout.
Current testing baseline focuses on tests/unit/.
For full test layout conventions, path mirroring, and scope guidance, see
tests/README.md.
The suggested path for a new package is to invoke
full-package-creation-flow from agents-repo/agents-repo-package-creation
after the draft pull request. That package is already extracted in this
repository (see IDE Setup); do not start with a separate CLI
install. The flow scaffolds with package:create, authors source, reviews
for submission readiness, and can run the pipeline below. The flow MAY exit
after any step; confirm the pipeline completed before marking the pull
request ready for review.
Contributors and AI agents work only on source files under the package root. The scripts manage all versioned artifacts. Manual authors MAY skip the flow and write those source files directly, then run the same pipeline.
# 1. Build and publish a version snapshot
npm run package:build -- --package <namespace>/<package-id>
# 2. Deep artifact verification
npm run package:validate-artifacts -- --package <namespace>/<package-id>
The package-build script automatically runs preflight validation equivalent
to package:validate before building artifacts. Scripts are intentionally
single-responsibility, and orchestration is still performed externally
(for example by CI or AI agents).
During development, you MAY run npm run package:validate -- --package <namespace>/<package-id>
manually to check the working state before the package is ready to build.
For package-script changes, use the separate smoke command:
npm run package:create:smoke -- --package <namespace>/<package-id>
# example: agents-repo/smoke-package
That smoke flow creates a temporary package workspace under
packages/agents-repo/<package-id>/ and runs the full script chain end to end:
package:create, package:validate, package:build, and
package:validate-artifacts.
npm run package:create:smoke -- --package agents-repo/smoke-package..github/workflows/agent-environment.yml.Package artifacts are designed for reuse in external projects, and downstream repositories with different linting rules need to adapt imported agent files or configure ignore rules on their side.
release/*.
ERR_OVERWRITE_PROTECTED_BRANCH. Publish a new semver instead.
In CI environments (GitHub Actions), the package-build script detects the
target branch using git rev-parse --abbrev-ref HEAD first, then falls back
to GitHub Actions environment variables (GITHUB_BASE_REF, GITHUB_REF_NAME)
if git returns HEAD (detached state). This ensures the protected-branch guard
works correctly in pull requests and tag builds, where the repository is
checked out in detached HEAD state. See specs/versioning-rules.md for details.
versions/All content under versions/ is generated exclusively by package-build,
except the one-time README backfill in specs/versioning-rules.md.
Contributors and AI agents MUST NOT manually create, modify, or remove any file
under versions/. See specs/package-format.md and specs/versioning-rules.md.
detail.json is generated by package-build and package-index-rebuild.
Contributors MUST NOT author it. See specs/package-detail-schema.md.
Package format:
<namespace>/
<package-id>/
metadata.json
README.md (optional)
detail.json (generated)
agents/
<agent-id>.agent.md
<agent-id>.metadata.json
flows/
<flow-id>.agent.md
<flow-id>.metadata.json
versions/
manifest.json
<version>/
metadata.json
README.md (when present at release)
agents/
<agent-id>.agent.md
<agent-id>.metadata.json
flows/
<flow-id>.agent.md
<flow-id>.metadata.json
<version>-<target-id>.zip
<version>-src.zip
Registry index:
packages/index.json lists all packages with summary fields for
webapp consumption, including package owner.packages/<namespace>/<package-id>/detail.json holds latest-snapshot
package detail for webapp pages. See specs/package-detail-schema.md.specs/index-schema.md for the index schema.Package rules:
agents/ or flows/ may be absent if unused.versions/manifest.json tracks all releases.versions/<version>/.versions/<version>/ must not be modified or removed
after publication.versions/<version>/metadata.json preserves the historical package metadata
for that release.versions/<version>/agents/ and versions/<version>/flows/ preserve the
historical source tree for that release.<version>-<target-id>.zip per built install
target and <version>-src.zip. Source archives exclude versions/ and
detail.json.v prefix.metadata.json and all .metadata.json sidecars must include a
schemaVersion supported by specs/schema-versions.json.metadata.json, agents/, and flows/ describe the
current working state.README.md may be used for package-level documentation;
when metadata quickstart is provided, it should point to this README..agent.md files in agents/ and flows/ must share the
same frontmatter version within a package.versions/manifest.json latest; at release
publication, it must match latest.agents/ and flows/.agents/*.agent.md and flows/*.agent.md
into a single agents/ folder for extraction into .github/.All normative specifications are stored in specs/
and written to be deterministic for AI and tool consumption.
Primary spec documents:
specs/package-format.mdspecs/package-detail-schema.mdspecs/metadata-schema.mdspecs/manifest-schema.mdspecs/agent-format.mdspecs/flow-format.mdspecs/versioning-rules.mdspecs/index-schema.mdspecs/chat-consumption.mdspecs/schema-versions.jsonThis repository is the catalog source of truth. It is one part of the agents-repo platform. For diagrams and end-to-end flows (publish, browse, install), see the organization Ecosystem overview.
For user guides and cross-repo documentation, see agents-repo.org/docs/. For this repository's overview on the public site, see agents-repo.org/repositories/registry/.
Presentation slides: docs/slides/README.md.
When you change a user-facing or contributor workflow in this
repository, update the corresponding page(s) in
agents-repo/webapp under
src/content/docs/ in the same PR or an immediate follow-up.
This repository is licensed under MIT.
Central open-source registry of AI agent configurations, developer workflows, skills, and runtime specifications. Compatible with CLI tools, IDE extension protocols, and MCP.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Registry 透過 stdio 在本機執行。
上次檢查時間:2026-11-13。 Central open-source registry of AI agent configurations, developer workflows, skills, and runtime specifications. Compatible with CLI tools, IDE extension protocols, and MCP.