[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79M546WGNYRMDDMN06V57FS":3,"skill-same:01M79M546WGNYRMDDMN06V57FS":53},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":33,"repositoryHtmlUrl":34,"repositoryHomepageUrl":35,"ownerHtmlUrl":36,"ownerBlogUrl":37,"ownerDescription":6,"updatedAt":38,"install":39,"resources":52},"01M79M546WGNYRMDDMN06V57FS","registry-authoring",null,"How to create and maintain a registry that agent-marketplace can discover, ingest, and sync into harness-native layouts. Use when creating a registry repo, adding skills, commands, subagents, hooks, MCP servers, or collections to one, writing registry CI validation, releasing a registry, or troubleshooting resources that are missing or malformed.","Adyen\u002Fagent-marketplace","Adyen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9713612?v=4","01M79KZGET744R01BG4Z41AKHA","01M79KZGFVFKFCS2KA7JQTBAWA",92,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fskills\u002Fregistry-authoring\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: registry-authoring\ndescription: >\n  How to create and maintain a registry that agent-marketplace can\n  discover, ingest, and sync into harness-native layouts. Use when creating\n  a registry repo, adding skills, commands, subagents, hooks, MCP servers, or\n  collections to one, writing registry CI validation, releasing a registry,\n  or troubleshooting resources that are missing or malformed.\nmetadata:\n  tags:\n    - registry\n    - skills\n    - authoring\n    - agent-marketplace\n---\n\n# Registry Authoring\n\nA registry is a plain Git repository (or local directory) whose resources are\ndiscovered from the native layout of one **source harness**. There is no\nmanifest: the CLI reads the layout's well-known paths. The authoritative\nreferences are\n[registry layout](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fregistry-layout.md),\n[resource metadata](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fresource-metadata.md),\nand [collections](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fcollections.md).\n\n## Minimal registry (Claude layout)\n\n```\nmy-registry\u002F\n├── skills\u002F\n│   ├── deploy-conventions\u002F\n│   │   ├── SKILL.md\n│   │   └── references\u002Fchecklist.md   ← ships with the skill\n│   └── incident-response\u002F\n│       └── SKILL.md\n├── commands\u002F\n│   └── release.md\n├── collections\u002F\n│   └── platform-onboarding\u002F\n│       └── COLLECTION.yaml\n├── CODEOWNERS\n└── README.md\n```\n\nA consumer selects from it with a v4 config:\n\n```yaml\n# .agents\u002Fconfig.yaml\napiVersion: agent-marketplace\u002Fv4\nsources:\n  platform:\n    git: git@github.com:example-org\u002Fmy-registry.git\n    ref: v1.4.0\n    source_harness: claude     # state the layout instead of relying on detection\nresources:\n  platform:\n    include:\n      - skill\u002Fdeploy-conventions\n      - command\u002Frelease\n      - collection\u002Fplatform-onboarding\n```\n\nConsumers can also select by `tags: [...]` or take everything with `all: true`.\nSet the source `path:` when resources live under a subdirectory: `path: resources`\ndiscovers `resources\u002Fskills\u002F...`, `resources\u002Fcommands\u002F...`, and so on.\n\n## Layout by source harness\n\nBundle and root-form paths are relative to the registry root, or to the\nsource's `path`.\n\n| Harness | Skill | Command | Subagent | Hook | MCP server |\n|---|---|---|---|---|---|\n| `claude` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `agents\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `.mcp.json` at the bundle root |\n| `factory` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `droids\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `mcp.json` |\n| `cursor` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `agents\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `mcp.json` |\n| `windsurf` | `skills\u002F\u003Cname>\u002FSKILL.md` | `workflows\u002F\u003Cname>.md` | not supported | `hooks.json` | `mcp_config.json` |\n| `gemini` | `.gemini\u002Fskills\u002F\u003Cname>\u002FSKILL.md` or `.agents\u002Fskills\u002F…` | `commands\u002F\u003Cname>.toml` | `.gemini\u002Fagents\u002F\u003Cname>.md` | `.gemini\u002Fsettings.json#hooks` | `.gemini\u002Fsettings.json#mcpServers` |\n| `devin` | `skills\u002F\u003Cname>\u002FSKILL.md` | skill dir + `x-agent-marketplace-kind: command` | `agents\u002F\u003Cname>.md` | `hooks.v1.json` | `mcp_config.json` |\n| `codex` | `.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | skill dir + `x-agent-marketplace-kind: command` | `.codex\u002Fagents\u002F\u003Cname>.toml` | `.codex\u002Fhooks.json#hooks` | `.codex\u002Fconfig.toml#mcp_servers` |\n| `opencode` | `.opencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `.opencode\u002Fcommands\u002F\u003Cname>.md` | `.opencode\u002Fagents\u002F\u003Cname>.md` | `.opencode\u002Fhooks\u002Fagent-marketplace\u002F\u003Cname>.json` | `opencode.json[c]#mcp` |\n\nThere are no generic `subagents\u002F` or `mcp\u002F` roots: a Claude subagent ships as\n`agents\u002F\u003Cname>.md`, and Claude MCP servers ship in a root `.mcp.json`. Files in\ndirectories the layout does not read are silently undiscovered. Explicit\nworkspace roots keep their resources inside the matching harness prefix; their\nhook files are listed below.\n\n### Hooks\n\nA registry may instead be an explicit native workspace root. Its hook file is:\n\n| Harness | Native workspace hook path |\n|---|---|\n| `claude` | `.claude\u002Fsettings.json#hooks` |\n| `factory` | `.factory\u002Fhooks.json` |\n| `cursor` | `.cursor\u002Fhooks.json#hooks` |\n| `windsurf` | `.devin\u002Fhooks.json#hooks` |\n| `gemini` | `.gemini\u002Fsettings.json#hooks` |\n| `devin` | `.devin\u002Fhooks.v1.json` |\n| `codex` | `.codex\u002Fhooks.json#hooks` |\n| `opencode` | `.opencode\u002Fhooks\u002Fagent-marketplace\u002F\u003Cname>.json` beside the fixed adapter |\n\nUse the source harness's documented workspace directories for its other\nresources. A Claude workspace source uses `.claude\u002Fskills\u002F`, `.claude\u002Fcommands\u002F`, `.claude\u002Fagents\u002F`, and\n`.claude\u002Fsettings.json` together; it does not mix root-level bundle directories\nor a `.claude-plugin` manifest with that workspace hook file.\n\nFor example, a Claude `PreToolUse` hook that runs only for `Bash` can ship in\n`.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"${CLAUDE_PLUGIN_ROOT}\u002F.claude\u002Fscripts\u002Fcheck.sh\\\"\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n`${CLAUDE_PLUGIN_ROOT}` is the bundle root, the folder that contains `.claude\u002F`,\nso the path after the token includes `.claude\u002F`. Keep `scripts\u002Fcheck.sh` below\n`.claude\u002F` beside the hook definition. Sync copies regular support files\nbyte-for-byte into `hook-support\u002F\u003Csource>\u002F\u003Chook>\u002F.claude\u002Fscripts\u002Fcheck.sh` for\neach selected target and rewrites the plugin-root token to that installed\nlocation. A command that omits `.claude\u002F`, such as\n`${CLAUDE_PLUGIN_ROOT}\u002Fscripts\u002Fcheck.sh`, still installs for one minor release\nwith a `hook.support-reference-legacy` warning; change it to the bundle-root\npath. Repository-scope commands use the target's documented\nproject-directory variable or working-directory base; user-scope commands use\nthe absolute installed path. The definition JSON itself is not copied into\nsupport output.\n\nHook matchers must cover the same source tool concepts exactly, including\nanchoring and MCP naming. A partial or unknown mapping suppresses that hook\nwith an error, while valid sibling hooks still install. The shipped\n[hook and tool catalog](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fhook-and-tool-names.md)\nlists the exact target events, types, names, and timeout rules. Do not expect\nevery resource with an explicit tool list to convert to every target; an\nallow-list can only select tools the target actually has, and it cannot use a\ncombined target tool to cover only part of that tool's scope.\n\nA hook command or prompt is trusted executable content. Review it as registry\ncode, and note that sync prints changed command and prompt values to stdout for\nreview. That stdout listing is intentionally exact; the application's logs and\ntelemetry do not contain those values.\n\n### Autodetection\n\nWithout `source_harness`, the CLI detects the layout from markers: `.devin\u002F`,\nthen plugin manifests (`.claude-plugin\u002Fplugin.json`, `.factory-plugin\u002F`,\n`.cursor-plugin\u002F`, `gemini-extension.json`), then `.codex\u002F`, then Claude-shaped\nroots, and so on. Root-level Cursor, Windsurf, Factory, and Gemini layouts share\nfolder names with Claude, and a root-level Devin layout (no `.devin\u002F`) is never\ndetected. `.devin\u002Fhooks.json` is Windsurf's workspace hook file, while\n`.devin\u002Fhooks.v1.json` is Devin CLI's; set `source_harness` explicitly when that\ncontext could be ambiguous. An `.opencode\u002F` folder with OpenCode resources or\n`opencode.json` selects OpenCode only when the otherwise-detected layout has no\nworkspace folder of its own (`.codex\u002F`, `.claude\u002F`, `.factory\u002F`, `.cursor\u002F`,\n`.gemini\u002F`, `.windsurf\u002F`); `.opencode\u002Fpackage.json` alone is not a marker. When\nboth layouts are present the catalog warns `ingest.autodetect.ambiguous`, and\nthe unselected layout is not read; a container of bundles with a top-level\n`.opencode\u002F` stays a container. Tell consumers to set `source_harness` for\nthese and the other ambiguous registries. An undetected registry falls back to\nClaude with `catalog.autodetect.fallback`.\n\n### Root shapes\n\nA registry root (or the `path` target) may be one bundle in a layout above, a\nsingle `SKILL.md` (which must declare `name`), a folder of skill folders, or a\npure container of bundles. A container's subfolders are searched for bundles,\nskipping `.git`, `.github`, `node_modules`, `.cache`, `test`, `tests`,\n`__tests__`, harness folders, and resource folders. A root that has its own\nresources and also sub-bundles is read as the root only, with\n`catalog.discover.sub-bundles-ignored`; move root resources into a subfolder\nsuch as `common\u002F`.\n\nEverything inside a skill folder ships with the skill; a nested `SKILL.md` is a\nsupport file, not a separate skill. Keep skills one level under `skills\u002F`.\n\n## `SKILL.md` frontmatter\n\nFollow the [Agent Skills specification](https:\u002F\u002Fagentskills.io\u002Fspecification):\n\n```markdown\n---\nname: vm-lifecycle\ndescription: >\n  Create, update, and decommission VMs. Use when working with OpenStack VMs,\n  Puppet node definitions, or DNS records for a host.\nlicense: Apache-2.0\nmetadata:\n  tags: [infra, openstack, puppet]\n  requires:\n    - mcp:service-catalog\n    - name: incident-response\n      kind: skill\n      registry: git@github.com:example-org\u002Foperations-skills.git\n      path: skills\n---\n```\n\n| Field | Notes |\n|---|---|\n| `name` | Lowercase letters, digits, hyphens; starts with a letter. Wins over the folder name; the folder name is the fallback, except for a root-level `SKILL.md`. Keep them equal. |\n| `description` | Required by the spec. Write it as a when-to-use trigger naming symptoms, tools, and error conditions. |\n| `license` | Optional SPDX identifier. Hosted Marketplaces use it for license policy. |\n| `x-agent-marketplace-kind` | `command` marks a skill-shaped command in Devin and Codex layouts only. |\n| `metadata.tags` | Strings used by consumer `tags:` and `install --tag`. Matching is exact and case-sensitive. |\n| `metadata.requires` | Advisory prerequisites. |\n\nInvalid YAML or an invalid name makes the skill malformed (for example\n`ingest.claude.load-skill-failed`): `list` shows `malformed: \u003Creason>`, sync\ncounts it under `Malformed`, and it is not installed. Harness-specific fields\nsuch as `allowed-tools` and `model` are translated per target; other unknown\nfields pass through.\n\nCommands and subagents written as Markdown with frontmatter read `metadata.tags`\nand `metadata.requires` from the same place. A Claude command's name comes from\nits file name.\n\n### Tags\n\nTags group resources for bulk selection. Use a small set (3–6) of lowercase\nnouns: one domain (`infra`, `security`, `platform`) plus technologies (`k8s`,\n`puppet`). A tag that repeats the resource name selects nothing new.\n\n### Prerequisites\n\n`requires` items are `\"\u003Ckind>:\u003Cname>\"` strings (a bare name means `skill`) or\nmaps with `name` and optional `kind`, `registry`, `path`. Kinds are `skill`,\n`command`, `subagent`, `hook`, `mcp`; `collection` is not accepted. A\nprerequisite is met by any selected resource of that kind and name, from any\nsource; `registry` and `path` only improve the suggested install command.\nUnmet prerequisites warn and never install anything. Items with an unknown kind\nor no `name` are skipped with a log warning.\n\n## Collections\n\nA collection bundles resources for one-line selection\n(`collection\u002F\u003Cname>` in a consumer's `include`). It lives at\n`collections\u002F\u003Cname>\u002FCOLLECTION.yaml`; flat `collections\u002F\u003Cname>.yaml` files are\nignored, and consumers match on the `name` field, not the folder.\n\n```yaml\nname: platform-onboarding\ndescription: Common starter resources for platform teams\nresources:\n  - kind: skill\n    name: deploy-conventions\n  - kind: command\n    name: release\n  - kind: mcp\n    name: service-catalog\n    registry: https:\u002F\u002Fgithub.com\u002Fexample-org\u002Fshared-mcp.git   # must already be a consumer source\nincludes:\n  - name: security-baseline\n```\n\n- Member `kind` defaults to `skill`; `collection` is not a member kind (use\n  `includes` to nest). The legacy `skills:` list still works; write `resources:`.\n- A member without `registry` comes from the collection's own source, ref, and\n  path. A collection cannot add a registry to the consumer's config; a member\n  from another registry fails unless the consumer already declares it.\n- `includes` may name a collection from any configured registry. Shared nested\n  collections are fine; including an ancestor is a cycle.\n- A missing member warns during `sync` and fails `sync --strict`; `list` does\n  not check members.\n- The collection itself writes no files; removing one member records an\n  exclude and keeps the collection selected.\n\n## Writing the body\n\nThe body is what the agent reads after the description fires. Put the ordered\nsteps first, then decision rules, reference tables, and gotchas. Name exact\nfiles, fields, and commands:\n\n```markdown\n## Step 1: Network configuration (network-configurations repo)\nAdd the VM's IP allocation in `networks\u002F\u003Cdc>\u002Fhosts.yaml` under the\ndatacenter section, with `hostname`, `ip`, and `netmask`.\n```\n\nReference support files from the body (`See references\u002Frepo-map.md`) so the\nagent knows to open them.\n\n## Check locally\n\n```bash\nagent-marketplace list --from .            # every resource should be `available`\n```\n\nA clean conversion reports `Diagnostics 0`. Look up `ingest.*` codes in the\n[diagnostics reference](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fdiagnostics.md).\n\n## CI validation\n\nSync a throwaway consumer against the checkout with a pinned CLI\n(`v4.0.9` or newer) and every harness your consumers target:\n\n> **Warning:** Hook review stdout includes exact command and prompt values.\n> This script deliberately captures that stdout in `sync.log`. Treat the log as\n> sensitive and do not publish it as a CI artifact.\n\n```bash\nset -euo pipefail                       # run under bash\nREGISTRY_PATH=$PWD\nCONSUMER=$(mktemp -d)\nmkdir -p \"$CONSUMER\u002F.agents\"\ncat > \"$CONSUMER\u002F.agents\u002Fconfig.yaml\" \u003C\u003C EOF\napiVersion: agent-marketplace\u002Fv4\nharnesses: [claude, factory, cursor, windsurf, gemini, devin, codex]\nsources:\n  checkout:\n    directory: ${REGISTRY_PATH}\nresources:\n  checkout:\n    all: true\n    required: true\nEOF\ncd \"$CONSUMER\"\nagent-marketplace sync --strict -v | tee sync.log\ngrep -q 'Malformed 0  Errors' sync.log   # --strict alone does not fail on malformed resources under all: true\nagent-marketplace sync --check\nfor kind in skill command subagent hook mcp collection; do agent-marketplace list --kind \"$kind\"; done\n```\n\nCompare the `list` output with a checked-in expectation so a resource in an\nunread directory fails CI. The\n[CI how-to](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Fhow-to\u002Fauthor\u002Fvalidate-a-registry-in-ci.md)\nexplains each step and the download command for a pinned release.\n\n## Access control\n\n`CODEOWNERS` plus branch protection is the trust boundary: whoever can merge\ninto the registry ships resources to every consumer. Require review for\n`skills\u002F` and stricter owners for sensitive paths.\n\n## Versioning and releases\n\n- Tag releases with semantic versions and keep a `CHANGELOG.md`. Renaming or\n  removing a resource is a major release.\n- Consumers pinned to a tag stay on it until they edit `ref:` and run `sync`.\n  Consumers on a branch stay on their locked commit until `update`.\n- `update --bump` rewrites eligible refs in v4 `sources:` to tags that differ\n  only in the final number. Refs declared by included fragments are reported\n  and left unchanged; consumers edit those fragments deliberately.\n- Document the consumer v4 snippet and contribution rules in the registry\n  README.\n\n## Common mistakes\n\n| Mistake | Symptom | Fix |\n|---|---|---|\n| Resource in a directory the layout does not read (`subagents\u002F`, `mcp\u002F`) | Missing from `list` | Use the source harness's native path |\n| Root-level Cursor\u002FWindsurf\u002FFactory\u002FDevin layout without `source_harness` | Read as Claude; resources missing | Consumers set `source_harness` |\n| Skill nested inside another skill | Inner skill not discovered | Keep skills one level under `skills\u002F` |\n| `name` with capitals, spaces, or underscores | Skill reported malformed | Use kebab-case matching the folder |\n| Root resources plus sub-bundles | `catalog.discover.sub-bundles-ignored` | Move root resources into a subfolder |\n| Collection as `collections\u002F\u003Cname>.yaml` | Collection not found | Use `collections\u002F\u003Cname>\u002FCOLLECTION.yaml` |\n| Collection member from an unconfigured registry | Expansion error | Tell consumers to add that source first |\n| Same kind and name in two registries | Consumer warns and picks one winner | Rename, or consumers narrow selections |\n| Vague description | Agents never activate the skill | Name triggers, tools, and error text |\n| No CODEOWNERS | Unreviewed changes reach consumers | Add CODEOWNERS and branch protection |\n","# Registry Authoring\n\nA registry is a plain Git repository (or local directory) whose resources are\ndiscovered from the native layout of one **source harness**. There is no\nmanifest: the CLI reads the layout's well-known paths. The authoritative\nreferences are\n[registry layout](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fregistry-layout.md),\n[resource metadata](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fresource-metadata.md),\nand [collections](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fcollections.md).\n\n## Minimal registry (Claude layout)\n\n```\nmy-registry\u002F\n├── skills\u002F\n│   ├── deploy-conventions\u002F\n│   │   ├── SKILL.md\n│   │   └── references\u002Fchecklist.md   ← ships with the skill\n│   └── incident-response\u002F\n│       └── SKILL.md\n├── commands\u002F\n│   └── release.md\n├── collections\u002F\n│   └── platform-onboarding\u002F\n│       └── COLLECTION.yaml\n├── CODEOWNERS\n└── README.md\n```\n\nA consumer selects from it with a v4 config:\n\n```yaml\n# .agents\u002Fconfig.yaml\napiVersion: agent-marketplace\u002Fv4\nsources:\n  platform:\n    git: git@github.com:example-org\u002Fmy-registry.git\n    ref: v1.4.0\n    source_harness: claude     # state the layout instead of relying on detection\nresources:\n  platform:\n    include:\n      - skill\u002Fdeploy-conventions\n      - command\u002Frelease\n      - collection\u002Fplatform-onboarding\n```\n\nConsumers can also select by `tags: [...]` or take everything with `all: true`.\nSet the source `path:` when resources live under a subdirectory: `path: resources`\ndiscovers `resources\u002Fskills\u002F...`, `resources\u002Fcommands\u002F...`, and so on.\n\n## Layout by source harness\n\nBundle and root-form paths are relative to the registry root, or to the\nsource's `path`.\n\n| Harness | Skill | Command | Subagent | Hook | MCP server |\n|---|---|---|---|---|---|\n| `claude` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `agents\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `.mcp.json` at the bundle root |\n| `factory` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `droids\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `mcp.json` |\n| `cursor` | `skills\u002F\u003Cname>\u002FSKILL.md` | `commands\u002F\u003Cname>.md` | `agents\u002F\u003Cname>.md` | `hooks\u002Fhooks.json` | `mcp.json` |\n| `windsurf` | `skills\u002F\u003Cname>\u002FSKILL.md` | `workflows\u002F\u003Cname>.md` | not supported | `hooks.json` | `mcp_config.json` |\n| `gemini` | `.gemini\u002Fskills\u002F\u003Cname>\u002FSKILL.md` or `.agents\u002Fskills\u002F…` | `commands\u002F\u003Cname>.toml` | `.gemini\u002Fagents\u002F\u003Cname>.md` | `.gemini\u002Fsettings.json#hooks` | `.gemini\u002Fsettings.json#mcpServers` |\n| `devin` | `skills\u002F\u003Cname>\u002FSKILL.md` | skill dir + `x-agent-marketplace-kind: command` | `agents\u002F\u003Cname>.md` | `hooks.v1.json` | `mcp_config.json` |\n| `codex` | `.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | skill dir + `x-agent-marketplace-kind: command` | `.codex\u002Fagents\u002F\u003Cname>.toml` | `.codex\u002Fhooks.json#hooks` | `.codex\u002Fconfig.toml#mcp_servers` |\n| `opencode` | `.opencode\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | `.opencode\u002Fcommands\u002F\u003Cname>.md` | `.opencode\u002Fagents\u002F\u003Cname>.md` | `.opencode\u002Fhooks\u002Fagent-marketplace\u002F\u003Cname>.json` | `opencode.json[c]#mcp` |\n\nThere are no generic `subagents\u002F` or `mcp\u002F` roots: a Claude subagent ships as\n`agents\u002F\u003Cname>.md`, and Claude MCP servers ship in a root `.mcp.json`. Files in\ndirectories the layout does not read are silently undiscovered. Explicit\nworkspace roots keep their resources inside the matching harness prefix; their\nhook files are listed below.\n\n### Hooks\n\nA registry may instead be an explicit native workspace root. Its hook file is:\n\n| Harness | Native workspace hook path |\n|---|---|\n| `claude` | `.claude\u002Fsettings.json#hooks` |\n| `factory` | `.factory\u002Fhooks.json` |\n| `cursor` | `.cursor\u002Fhooks.json#hooks` |\n| `windsurf` | `.devin\u002Fhooks.json#hooks` |\n| `gemini` | `.gemini\u002Fsettings.json#hooks` |\n| `devin` | `.devin\u002Fhooks.v1.json` |\n| `codex` | `.codex\u002Fhooks.json#hooks` |\n| `opencode` | `.opencode\u002Fhooks\u002Fagent-marketplace\u002F\u003Cname>.json` beside the fixed adapter |\n\nUse the source harness's documented workspace directories for its other\nresources. A Claude workspace source uses `.claude\u002Fskills\u002F`, `.claude\u002Fcommands\u002F`, `.claude\u002Fagents\u002F`, and\n`.claude\u002Fsettings.json` together; it does not mix root-level bundle directories\nor a `.claude-plugin` manifest with that workspace hook file.\n\nFor example, a Claude `PreToolUse` hook that runs only for `Bash` can ship in\n`.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"${CLAUDE_PLUGIN_ROOT}\u002F.claude\u002Fscripts\u002Fcheck.sh\\\"\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n`${CLAUDE_PLUGIN_ROOT}` is the bundle root, the folder that contains `.claude\u002F`,\nso the path after the token includes `.claude\u002F`. Keep `scripts\u002Fcheck.sh` below\n`.claude\u002F` beside the hook definition. Sync copies regular support files\nbyte-for-byte into `hook-support\u002F\u003Csource>\u002F\u003Chook>\u002F.claude\u002Fscripts\u002Fcheck.sh` for\neach selected target and rewrites the plugin-root token to that installed\nlocation. A command that omits `.claude\u002F`, such as\n`${CLAUDE_PLUGIN_ROOT}\u002Fscripts\u002Fcheck.sh`, still installs for one minor release\nwith a `hook.support-reference-legacy` warning; change it to the bundle-root\npath. Repository-scope commands use the target's documented\nproject-directory variable or working-directory base; user-scope commands use\nthe absolute installed path. The definition JSON itself is not copied into\nsupport output.\n\nHook matchers must cover the same source tool concepts exactly, including\nanchoring and MCP naming. A partial or unknown mapping suppresses that hook\nwith an error, while valid sibling hooks still install. The shipped\n[hook and tool catalog](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fhook-and-tool-names.md)\nlists the exact target events, types, names, and timeout rules. Do not expect\nevery resource with an explicit tool list to convert to every target; an\nallow-list can only select tools the target actually has, and it cannot use a\ncombined target tool to cover only part of that tool's scope.\n\nA hook command or prompt is trusted executable content. Review it as registry\ncode, and note that sync prints changed command and prompt values to stdout for\nreview. That stdout listing is intentionally exact; the application's logs and\ntelemetry do not contain those values.\n\n### Autodetection\n\nWithout `source_harness`, the CLI detects the layout from markers: `.devin\u002F`,\nthen plugin manifests (`.claude-plugin\u002Fplugin.json`, `.factory-plugin\u002F`,\n`.cursor-plugin\u002F`, `gemini-extension.json`), then `.codex\u002F`, then Claude-shaped\nroots, and so on. Root-level Cursor, Windsurf, Factory, and Gemini layouts share\nfolder names with Claude, and a root-level Devin layout (no `.devin\u002F`) is never\ndetected. `.devin\u002Fhooks.json` is Windsurf's workspace hook file, while\n`.devin\u002Fhooks.v1.json` is Devin CLI's; set `source_harness` explicitly when that\ncontext could be ambiguous. An `.opencode\u002F` folder with OpenCode resources or\n`opencode.json` selects OpenCode only when the otherwise-detected layout has no\nworkspace folder of its own (`.codex\u002F`, `.claude\u002F`, `.factory\u002F`, `.cursor\u002F`,\n`.gemini\u002F`, `.windsurf\u002F`); `.opencode\u002Fpackage.json` alone is not a marker. When\nboth layouts are present the catalog warns `ingest.autodetect.ambiguous`, and\nthe unselected layout is not read; a container of bundles with a top-level\n`.opencode\u002F` stays a container. Tell consumers to set `source_harness` for\nthese and the other ambiguous registries. An undetected registry falls back to\nClaude with `catalog.autodetect.fallback`.\n\n### Root shapes\n\nA registry root (or the `path` target) may be one bundle in a layout above, a\nsingle `SKILL.md` (which must declare `name`), a folder of skill folders, or a\npure container of bundles. A container's subfolders are searched for bundles,\nskipping `.git`, `.github`, `node_modules`, `.cache`, `test`, `tests`,\n`__tests__`, harness folders, and resource folders. A root that has its own\nresources and also sub-bundles is read as the root only, with\n`catalog.discover.sub-bundles-ignored`; move root resources into a subfolder\nsuch as `common\u002F`.\n\nEverything inside a skill folder ships with the skill; a nested `SKILL.md` is a\nsupport file, not a separate skill. Keep skills one level under `skills\u002F`.\n\n## `SKILL.md` frontmatter\n\nFollow the [Agent Skills specification](https:\u002F\u002Fagentskills.io\u002Fspecification):\n\n```markdown\n---\nname: vm-lifecycle\ndescription: >\n  Create, update, and decommission VMs. Use when working with OpenStack VMs,\n  Puppet node definitions, or DNS records for a host.\nlicense: Apache-2.0\nmetadata:\n  tags: [infra, openstack, puppet]\n  requires:\n    - mcp:service-catalog\n    - name: incident-response\n      kind: skill\n      registry: git@github.com:example-org\u002Foperations-skills.git\n      path: skills\n---\n```\n\n| Field | Notes |\n|---|---|\n| `name` | Lowercase letters, digits, hyphens; starts with a letter. Wins over the folder name; the folder name is the fallback, except for a root-level `SKILL.md`. Keep them equal. |\n| `description` | Required by the spec. Write it as a when-to-use trigger naming symptoms, tools, and error conditions. |\n| `license` | Optional SPDX identifier. Hosted Marketplaces use it for license policy. |\n| `x-agent-marketplace-kind` | `command` marks a skill-shaped command in Devin and Codex layouts only. |\n| `metadata.tags` | Strings used by consumer `tags:` and `install --tag`. Matching is exact and case-sensitive. |\n| `metadata.requires` | Advisory prerequisites. |\n\nInvalid YAML or an invalid name makes the skill malformed (for example\n`ingest.claude.load-skill-failed`): `list` shows `malformed: \u003Creason>`, sync\ncounts it under `Malformed`, and it is not installed. Harness-specific fields\nsuch as `allowed-tools` and `model` are translated per target; other unknown\nfields pass through.\n\nCommands and subagents written as Markdown with frontmatter read `metadata.tags`\nand `metadata.requires` from the same place. A Claude command's name comes from\nits file name.\n\n### Tags\n\nTags group resources for bulk selection. Use a small set (3–6) of lowercase\nnouns: one domain (`infra`, `security`, `platform`) plus technologies (`k8s`,\n`puppet`). A tag that repeats the resource name selects nothing new.\n\n### Prerequisites\n\n`requires` items are `\"\u003Ckind>:\u003Cname>\"` strings (a bare name means `skill`) or\nmaps with `name` and optional `kind`, `registry`, `path`. Kinds are `skill`,\n`command`, `subagent`, `hook`, `mcp`; `collection` is not accepted. A\nprerequisite is met by any selected resource of that kind and name, from any\nsource; `registry` and `path` only improve the suggested install command.\nUnmet prerequisites warn and never install anything. Items with an unknown kind\nor no `name` are skipped with a log warning.\n\n## Collections\n\nA collection bundles resources for one-line selection\n(`collection\u002F\u003Cname>` in a consumer's `include`). It lives at\n`collections\u002F\u003Cname>\u002FCOLLECTION.yaml`; flat `collections\u002F\u003Cname>.yaml` files are\nignored, and consumers match on the `name` field, not the folder.\n\n```yaml\nname: platform-onboarding\ndescription: Common starter resources for platform teams\nresources:\n  - kind: skill\n    name: deploy-conventions\n  - kind: command\n    name: release\n  - kind: mcp\n    name: service-catalog\n    registry: https:\u002F\u002Fgithub.com\u002Fexample-org\u002Fshared-mcp.git   # must already be a consumer source\nincludes:\n  - name: security-baseline\n```\n\n- Member `kind` defaults to `skill`; `collection` is not a member kind (use\n  `includes` to nest). The legacy `skills:` list still works; write `resources:`.\n- A member without `registry` comes from the collection's own source, ref, and\n  path. A collection cannot add a registry to the consumer's config; a member\n  from another registry fails unless the consumer already declares it.\n- `includes` may name a collection from any configured registry. Shared nested\n  collections are fine; including an ancestor is a cycle.\n- A missing member warns during `sync` and fails `sync --strict`; `list` does\n  not check members.\n- The collection itself writes no files; removing one member records an\n  exclude and keeps the collection selected.\n\n## Writing the body\n\nThe body is what the agent reads after the description fires. Put the ordered\nsteps first, then decision rules, reference tables, and gotchas. Name exact\nfiles, fields, and commands:\n\n```markdown\n## Step 1: Network configuration (network-configurations repo)\nAdd the VM's IP allocation in `networks\u002F\u003Cdc>\u002Fhosts.yaml` under the\ndatacenter section, with `hostname`, `ip`, and `netmask`.\n```\n\nReference support files from the body (`See references\u002Frepo-map.md`) so the\nagent knows to open them.\n\n## Check locally\n\n```bash\nagent-marketplace list --from .            # every resource should be `available`\n```\n\nA clean conversion reports `Diagnostics 0`. Look up `ingest.*` codes in the\n[diagnostics reference](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Freference\u002Fdiagnostics.md).\n\n## CI validation\n\nSync a throwaway consumer against the checkout with a pinned CLI\n(`v4.0.9` or newer) and every harness your consumers target:\n\n> **Warning:** Hook review stdout includes exact command and prompt values.\n> This script deliberately captures that stdout in `sync.log`. Treat the log as\n> sensitive and do not publish it as a CI artifact.\n\n```bash\nset -euo pipefail                       # run under bash\nREGISTRY_PATH=$PWD\nCONSUMER=$(mktemp -d)\nmkdir -p \"$CONSUMER\u002F.agents\"\ncat > \"$CONSUMER\u002F.agents\u002Fconfig.yaml\" \u003C\u003C EOF\napiVersion: agent-marketplace\u002Fv4\nharnesses: [claude, factory, cursor, windsurf, gemini, devin, codex]\nsources:\n  checkout:\n    directory: ${REGISTRY_PATH}\nresources:\n  checkout:\n    all: true\n    required: true\nEOF\ncd \"$CONSUMER\"\nagent-marketplace sync --strict -v | tee sync.log\ngrep -q 'Malformed 0  Errors' sync.log   # --strict alone does not fail on malformed resources under all: true\nagent-marketplace sync --check\nfor kind in skill command subagent hook mcp collection; do agent-marketplace list --kind \"$kind\"; done\n```\n\nCompare the `list` output with a checked-in expectation so a resource in an\nunread directory fails CI. The\n[CI how-to](https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fsite\u002Fdocs\u002Fhow-to\u002Fauthor\u002Fvalidate-a-registry-in-ci.md)\nexplains each step and the download command for a pinned release.\n\n## Access control\n\n`CODEOWNERS` plus branch protection is the trust boundary: whoever can merge\ninto the registry ships resources to every consumer. Require review for\n`skills\u002F` and stricter owners for sensitive paths.\n\n## Versioning and releases\n\n- Tag releases with semantic versions and keep a `CHANGELOG.md`. Renaming or\n  removing a resource is a major release.\n- Consumers pinned to a tag stay on it until they edit `ref:` and run `sync`.\n  Consumers on a branch stay on their locked commit until `update`.\n- `update --bump` rewrites eligible refs in v4 `sources:` to tags that differ\n  only in the final number. Refs declared by included fragments are reported\n  and left unchanged; consumers edit those fragments deliberately.\n- Document the consumer v4 snippet and contribution rules in the registry\n  README.\n\n## Common mistakes\n\n| Mistake | Symptom | Fix |\n|---|---|---|\n| Resource in a directory the layout does not read (`subagents\u002F`, `mcp\u002F`) | Missing from `list` | Use the source harness's native path |\n| Root-level Cursor\u002FWindsurf\u002FFactory\u002FDevin layout without `source_harness` | Read as Claude; resources missing | Consumers set `source_harness` |\n| Skill nested inside another skill | Inner skill not discovered | Keep skills one level under `skills\u002F` |\n| `name` with capitals, spaces, or underscores | Skill reported malformed | Use kebab-case matching the folder |\n| Root resources plus sub-bundles | `catalog.discover.sub-bundles-ignored` | Move root resources into a subfolder |\n| Collection as `collections\u002F\u003Cname>.yaml` | Collection not found | Use `collections\u002F\u003Cname>\u002FCOLLECTION.yaml` |\n| Collection member from an unconfigured registry | Expansion error | Tell consumers to add that source first |\n| Same kind and name in two registries | Consumer warns and picks one winner | Rename, or consumers narrow selections |\n| Vague description | Agents never activate the skill | Name triggers, tools, and error text |\n| No CODEOWNERS | Unreviewed changes reach consumers | Add CODEOWNERS and branch protection |\n",{"name":5,"metadata":23,"description":29},{"tags":24},[25,26,27,28],"registry","skills","authoring","agent-marketplace","How to create and maintain a registry that agent-marketplace can discover, ingest, and sync into harness-native layouts. Use when creating a registry repo, adding skills, commands, subagents, hooks, MCP servers, or collections to one, writing registry CI validation, releasing a registry, or troubleshooting resources that are missing or malformed.\n","main","75e0f3781ee8523700058c36a01961f93be5be89","skills\u002Fregistry-authoring",5,"https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace","https:\u002F\u002Fagent-marketplace.io","https:\u002F\u002Fgithub.com\u002FAdyen","adyen.com","2026-11-15 04:37:04",{"source":8,"skillName":5,"commands":40,"prompt":50,"zipAvailable":51},[41,44,47],{"tool":42,"command":43},"npx","npx skills add Adyen\u002Fagent-marketplace --skill registry-authoring",{"tool":45,"command":46},"bunx","bunx skills add Adyen\u002Fagent-marketplace --skill registry-authoring",{"tool":48,"command":49},"pnpm","pnpm dlx skills add Adyen\u002Fagent-marketplace --skill registry-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fskills\u002Fregistry-authoring\u002FSKILL.md",true,[],[54,61,68,74,81,88],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":18},"01M79M5C4NVX43MJ0VTB12P25F","greeting","A simple example skill that greets the user","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Ftestdata\u002Fexample-skills-registry\u002Fskills\u002Fgreeting\u002FSKILL.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":18},"01M79M59F0JDP99KPDXJ628X9Y","code-explainer","Explains code snippets in plain language","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Ftestdata\u002Fexample-combined-registry\u002Fskills\u002Fcode-explainer\u002FSKILL.md",[],[],{"skillNo":69,"name":28,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M79M4XZ6Q9340PPTPV0JZ18C","How to use the agent-marketplace CLI to install shared AI agent resources from Git, directory, or hosted Marketplace sources and materialize them into native harness layouts. Use when setting up a repo, writing `.agents\u002Fconfig.yaml`, installing\u002Fremoving skills, commands, subagents, hooks, MCP servers, or collections, checking sync drift, updating locks, preparing pre-upgrade configuration conversion, or repairing shared harness config ownership.","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fskills\u002Fagent-marketplace\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":18},"01M79M4ND8VP3NGSY1JMT2E9YD","agent-marketplace-development","How to develop on the agent-marketplace codebase itself: architecture tour, testing workflow, TUI (Bubble Tea) and CLI (Cobra) conventions, and the config\u002Fresolver\u002Fmaterialization invariants that every change must preserve. Use when adding features, fixing bugs, or reviewing changes to the agent-marketplace Go binary, running local TUI QA, or maintaining harness compatibility validation. Every TUI change must ship a real-terminal TUI QA journey that proves the changed flow.","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fskills\u002Fagent-marketplace-development\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M79M4KMFK19FXXGY2SW6V5ZW","demo-skill","Demo skill for golden testing","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fpkg\u002Fharness-compilation\u002Ftestdata\u002Fresources\u002Fskills\u002Fdemo-skill\u002FSKILL.md",[],[],{"skillNo":89,"name":83,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":18},"01M79M4GJNSKNYCYDSDRTMQX01","https:\u002F\u002Fgithub.com\u002FAdyen\u002Fagent-marketplace\u002Fblob\u002Fmain\u002Fpkg\u002Fharness-compilation\u002Ftestdata\u002Fmatrix\u002Fskill\u002Finputs\u002Fwindsurf\u002F.windsurf\u002Fskills\u002Fdemo-skill\u002FSKILL.md",[],[]]