AGENTS.md git:20261017.9673b18A

Immutable. This exact content never changes and is served at /api/v1/blob/c3e922d9b05bb846.

# Repository guidance for agents

## Commands

Use the repository commands for repository layout, governance records, and validation. When creating or substantially revising a portable skill, use `skill-creator` as the primary authoring workflow, then review the current [Agent Skills frontmatter specification](https://agentskills.io/specification#frontmatter) for the complete supported frontmatter surface. Consider every element the specification currently defines, including elements that `skill-creator` may not yet surface, and apply the elements relevant to the skill.

```bash
npm run skill:new -- <skill-name>
npm run validate
npm run catalog:build
npm run catalog:check
npm run test:unit
npm run version:check
npm run skills:version-check -- --base origin/main
npm run commits:check -- --base origin/main
```

## Commits, versions, and releases

1. Write commit messages as `feat: …`, `fix: …`, `docs: …`, `chore: …`. CI now rejects anything else.
2. When you change a skill, bump its `metadata.version` and add a changelog entry in the same PR. CI blocks it otherwise.
3. When you're ready to ship, merge the open `chore: release X.Y.Z` PR. That's the whole release.

Release notes and the plugin version are generated from commit messages by release-please. `main` accepts changes only through pull requests with a passing `validate` check. Details are in CONTRIBUTING.md, Releases.

## Boundaries and standards

- Use the [Agent Skills reference site](https://agentskills.io/home) for ecosystem and authoring guidance. The [Agent Skills specification](https://agentskills.io/specification) takes precedence for content under `skills/<skill-name>/`.
- Keep portable packages in `skills/`; keep KuudoAI governance metadata in `catalog/entries/` and certification cases in `evals/`. The catalog is the repository's user-facing index: generated `catalog/skills.json` combines each skill's Agent Skills frontmatter with its review status, provenance, maintainers, and registry metadata.
- Certification, provenance, registry metadata, and client-specific information are repository policy, not required portable-skill metadata.
- Do not add client-specific files or metadata as a certification requirement.
- All KuudoAI-authored repository content is licensed under PolyForm Shield 1.0.0; `LICENSE.md` records the terms. Every first-party skill carries `license` frontmatter and a `LICENSE.txt` copied from `templates/LICENSE.txt.tmpl`; keep the copies identical, and set first-party catalog entries to `PolyForm-Shield-1.0.0`.

## Suite architecture

- Host adapters contain mechanics only: package discovery and the minimum host-specific bootstrap injection.
- `skills/using-kuudo/SKILL.md` contains the replaceable product and routing context. Change that context only in response to observed client behavior or an explicit product requirement; do not guess future routing policy.
- Never add synthetic MCP aliases, a capability registry, a routing runtime, or a client-config proxy.
- Keep `package.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and `.codex-plugin/plugin.json` versions synchronized.
- Every first-party `amazon-ads-*` consumer skill must include this recovery pointer; `amazon-ads-accounts` itself and imported third-party packages are exempt:

  > ## Account-context recovery
  >
  > If Amazon account scope, identifier type, marketplace mapping, or account relationships become unclear, consult `amazon-ads-accounts` when it is available. Resume this skill after resolving the ambiguity. If it is unavailable, use equivalent read-only discovery and ask the user when multiple valid choices remain. Never guess or interchange identifier types.

## Generated artifacts

`catalog/skills.json`, `THIRD_PARTY_NOTICES.md`, and, when there is at least one catalog entry, `skills.sh.json` are generated by `npm run catalog:build`. Do not edit them by hand; run `npm run catalog:check` before submitting changes. An empty repository intentionally has no catalog index or `skills.sh.json` because there are no skills to publish.

`THIRD_PARTY_NOTICES.md` covers cataloged third-party skills only. For non-skill derived infrastructure, preserve the upstream license under `licenses/` and add a public attribution link from the repository documentation.

`.github/CODEOWNERS` assigns review ownership; branch protection remains a repository setting and is not established by this file.

## Third-party content

Preserve imported third-party package contents and upstream license terms. Do not add KuudoAI metadata inside imported packages. Record an HTTPS source repository, immutable Git revision, source path, and license in the corresponding catalog entry; inspect external instructions and scripts before execution.