adyen/agent-marketplace/registry-authoring

Registry Authoring

A registry is a plain Git repository (or local directory) whose resources are discovered from the native layout of one source harness. There is no manifest: the CLI reads the layout's well-known paths. The authoritative references are registry layout, resource metadata, and collections.

Minimal registry (Claude layout)

my-registry/
├── skills/
│   ├── deploy-conventions/
│   │   ├── SKILL.md
│   │   └── references/checklist.md   ← ships with the skill
│   └── incident-response/
│       └── SKILL.md
├── commands/
│   └── release.md
├── collections/
│   └── platform-onboarding/
│       └── COLLECTION.yaml
├── CODEOWNERS
└── README.md

A consumer selects from it with a v4 config:

# .agents/config.yaml
apiVersion: agent-marketplace/v4
sources:
  platform:
    git: git@github.com:example-org/my-registry.git
    ref: v1.4.0
    source_harness: claude     # state the layout instead of relying on detection
resources:
  platform:
    include:
      - skill/deploy-conventions
      - command/release
      - collection/platform-onboarding

Consumers can also select by tags: [...] or take everything with all: true. Set the source path: when resources live under a subdirectory: path: resources discovers resources/skills/..., resources/commands/..., and so on.

Layout by source harness

Bundle and root-form paths are relative to the registry root, or to the source's path.

There are no generic subagents/ or mcp/ roots: a Claude subagent ships as agents/<name>.md, and Claude MCP servers ship in a root .mcp.json. Files in directories the layout does not read are silently undiscovered. Explicit workspace roots keep their resources inside the matching harness prefix; their hook files are listed below.

Hooks

A registry may instead be an explicit native workspace root. Its hook file is:

Use the source harness's documented workspace directories for its other resources. A Claude workspace source uses .claude/skills/, .claude/commands/, .claude/agents/, and .claude/settings.json together; it does not mix root-level bundle directories or a .claude-plugin manifest with that workspace hook file.

For example, a Claude PreToolUse hook that runs only for Bash can ship in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/.claude/scripts/check.sh\""
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} is the bundle root, the folder that contains .claude/, so the path after the token includes .claude/. Keep scripts/check.sh below .claude/ beside the hook definition. Sync copies regular support files byte-for-byte into hook-support/<source>/<hook>/.claude/scripts/check.sh for each selected target and rewrites the plugin-root token to that installed location. A command that omits .claude/, such as ${CLAUDE_PLUGIN_ROOT}/scripts/check.sh, still installs for one minor release with a hook.support-reference-legacy warning; change it to the bundle-root path. Repository-scope commands use the target's documented project-directory variable or working-directory base; user-scope commands use the absolute installed path. The definition JSON itself is not copied into support output.

Hook matchers must cover the same source tool concepts exactly, including anchoring and MCP naming. A partial or unknown mapping suppresses that hook with an error, while valid sibling hooks still install. The shipped hook and tool catalog lists the exact target events, types, names, and timeout rules. Do not expect every resource with an explicit tool list to convert to every target; an allow-list can only select tools the target actually has, and it cannot use a combined target tool to cover only part of that tool's scope.

A hook command or prompt is trusted executable content. Review it as registry code, and note that sync prints changed command and prompt values to stdout for review. That stdout listing is intentionally exact; the application's logs and telemetry do not contain those values.

Autodetection

Without source_harness, the CLI detects the layout from markers: .devin/, then plugin manifests (.claude-plugin/plugin.json, .factory-plugin/, .cursor-plugin/, gemini-extension.json), then .codex/, then Claude-shaped roots, and so on. Root-level Cursor, Windsurf, Factory, and Gemini layouts share folder names with Claude, and a root-level Devin layout (no .devin/) is never detected. .devin/hooks.json is Windsurf's workspace hook file, while .devin/hooks.v1.json is Devin CLI's; set source_harness explicitly when that context could be ambiguous. An .opencode/ folder with OpenCode resources or opencode.json selects OpenCode only when the otherwise-detected layout has no workspace folder of its own (.codex/, .claude/, .factory/, .cursor/, .gemini/, .windsurf/); .opencode/package.json alone is not a marker. When both layouts are present the catalog warns ingest.autodetect.ambiguous, and the unselected layout is not read; a container of bundles with a top-level .opencode/ stays a container. Tell consumers to set source_harness for these and the other ambiguous registries. An undetected registry falls back to Claude with catalog.autodetect.fallback.

Root shapes

A registry root (or the path target) may be one bundle in a layout above, a single SKILL.md (which must declare name), a folder of skill folders, or a pure container of bundles. A container's subfolders are searched for bundles, skipping .git, .github, node_modules, .cache, test, tests, __tests__, harness folders, and resource folders. A root that has its own resources and also sub-bundles is read as the root only, with catalog.discover.sub-bundles-ignored; move root resources into a subfolder such as common/.

Everything inside a skill folder ships with the skill; a nested SKILL.md is a support file, not a separate skill. Keep skills one level under skills/.

SKILL.md frontmatter

Follow the Agent Skills specification:

---
name: vm-lifecycle
description: >
  Create, update, and decommission VMs. Use when working with OpenStack VMs,
  Puppet node definitions, or DNS records for a host.
license: Apache-2.0
metadata:
  tags: [infra, openstack, puppet]
  requires:
    -mcp:service-catalog
    -name: incident-response
      kind: skill
      registry: git@github.com:example-org/operations-skills.git
      path: skills
---

Invalid YAML or an invalid name makes the skill malformed (for example ingest.claude.load-skill-failed): list shows malformed: <reason>, sync counts it under Malformed, and it is not installed. Harness-specific fields such as allowed-tools and model are translated per target; other unknown fields pass through.

Commands and subagents written as Markdown with frontmatter read metadata.tags and metadata.requires from the same place. A Claude command's name comes from its file name.

Tags

Tags group resources for bulk selection. Use a small set (3–6) of lowercase nouns: one domain (infra, security, platform) plus technologies (k8s, puppet). A tag that repeats the resource name selects nothing new.

Prerequisites

requires items are "<kind>:<name>" strings (a bare name means skill) or maps with name and optional kind, registry, path. Kinds are skill, command, subagent, hook, mcp; collection is not accepted. A prerequisite is met by any selected resource of that kind and name, from any source; registry and path only improve the suggested install command. Unmet prerequisites warn and never install anything. Items with an unknown kind or no name are skipped with a log warning.

Collections

A collection bundles resources for one-line selection (collection/<name> in a consumer's include). It lives at collections/<name>/COLLECTION.yaml; flat collections/<name>.yaml files are ignored, and consumers match on the name field, not the folder.

name: platform-onboarding
description: Common starter resources for platform teams
resources:
  - kind: skill
    name: deploy-conventions
  - kind: command
    name: release
  - kind: mcp
    name: service-catalog
    registry: https://github.com/example-org/shared-mcp.git   # must already be a consumer source
includes:
  - name: security-baseline