Add Claude Code plugin marketplace and agent skill for the gddy CLI

.agents/skills/gddy/README.md

@@ -0,0 +1,30 @@
+# gddy skill
+
+Teaches an AI coding agent how to drive `gddy`, GoDaddy's beta CLI for domain search, registration, and DNS management. It covers install/auth, the two-step quote-then-purchase flow for buying a domain, DNS record semantics (`add` vs `set` vs `delete`), and — since `gddy` moves faster than its own docs — how to fetch GoDaddy's developer docs correctly and when to trust `gddy --help` over a doc page.
+
+See [SKILL.md](./SKILL.md) for the full instructions given to the agent.
+
+## Installation
+
+### Claude Code
+
+```bash
+claude plugin marketplace add godaddy/cli
+claude plugin install godaddy-cli@godaddy
+```
+
+This installs the plugin that bundles both skills in this repo (`godaddy-cli` and `gddy`); Claude picks whichever one fits the task automatically.
+
+### Any other AI coding agent
+
+This repo is also compatible with [skills](https://github.com/vercel-labs/skills), a package-manager-style installer for agent skills that isn't tied to Claude Code — it supports Cursor, Codex, Windsurf, opencode, and 70+ other agents in addition to Claude Code:
+
+```bash
+npx skills add godaddy/cli --skill gddy --agent claude-code
+```
+
+Swap `--agent claude-code` for whichever agent you use (`cursor`, `codex`, `windsurf`, `opencode`, ...). Run `npx skills add --help` for the full list of supported agents.
+
+## What it doesn't cover
+
+Applications, auth, environments, releases/deploys, extensions, and webhooks live in a separate, older tool, `godaddy`, with its own skill — see [../godaddy-cli/README.md](../godaddy-cli/README.md).

.agents/skills/gddy/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gddy
+description: Use GoDaddy's beta CLI (`gddy`) to search, register, and manage domains and DNS records. Load this skill whenever a task involves running `gddy` commands, parsing their JSON output, finding or buying a domain, or editing DNS records (A, CNAME, MX, TXT, etc.) for a domain hosted at GoDaddy. `gddy` is a separate tool from GoDaddy's older `godaddy` CLI (applications, deployments, webhooks) — do not use this skill for that tool, and don't trigger for other registrars or DNS providers (Cloudflare, Route 53, Namecheap, etc.) unless GoDaddy is explicitly involved.
+---
+
+# gddy — GoDaddy domains & DNS CLI
+
+`gddy` is GoDaddy's beta CLI for domain search, registration, and DNS management. It's a separate, independently-installed tool from GoDaddy's older `godaddy` CLI (applications, deployments, webhooks) — different binary, different install method, different auth and config. Installing or using one doesn't affect the other. For application, deployment, or webhook tasks, use the `godaddy-cli` skill instead of this one.
+
+Both tools exist side by side because `gddy` is the newer of the two and under active development, with more surface area on its roadmap than what's documented here — it already has early, not-yet-stable support for things like applications and webhooks alongside its domain/DNS focus. Stick to the domain/DNS commands documented in this skill unless you've confirmed a newer capability is ready via `gddy --help`.
+
+It's under active development, and moves faster than its own docs and README — see "When the CLI and the docs disagree" below.
+
+## Setup
+
+Install:
+
+```bash
+# macOS / Linux / Git Bash / MSYS2 / Cygwin
+curl -fsSL https://github.com/godaddy/cli/releases/latest/download/install.sh | bash
+
+# PowerShell
+irm https://github.com/godaddy/cli/releases/latest/download/install.ps1 | iex
+```
+
+Verify with `gddy --version`. This installs the `gddy` binary alongside any existing `godaddy` CLI — the two are separate tools.
+
+Authenticate with `gddy auth login` (opens a browser for OAuth). Check state with `gddy auth status`, sign out with `gddy auth logout`. For non-interactive use (CI, scripts), use a Personal Access Token instead — manage one with `gddy pat add/list/remove`, or set the `GDDY_PAT`/`GDDY_PAT_<ENV>` env var directly (checked before OAuth). Note PATs can't do everything: domain purchase specifically requires a customer-scoped OAuth login (see below).
+
+Every command accepts `--env <ote|prod>` to pick environment (default `prod`) and `--debug` for verbose output.
+
+## When the CLI and the docs disagree, trust the CLI
+
+`gddy`'s own `--help` output reflects the actual installed version; docs and the README can lag behind a release, since it's beta and moves fast. Before relying on a remembered or documented flag shape, especially for anything destructive or paid, run `gddy <command> --help` and trust that over any doc page or README. This matters most for domain purchase, which is a two-step flow that some docs oversimplify (see below).
+
+## Domain purchase: it's a two-step quote-then-purchase flow, not one command
+
+This is the highest-stakes command in the CLI — it charges money and can't be undone — so get the shape right. Some docs and even the README show it as a single `gddy domain purchase <domain> --agree --confirm` call; that's a simplification and doesn't match what the CLI actually does. The real flow locks in registration terms first, then executes against that locked quote:
+
+1. **Quote** — run `gddy domain quote --help` for the full flag list (period, privacy, nameservers, etc. all get baked into the quote token). Returns a single-use `quoteToken` valid for roughly 10 minutes, cached locally alongside the contacts file.
+
+2. **Purchase** — run `gddy domain purchase --help` for the full flag list. `--agree` means "I consent to this quote's required legal agreements" — leave it off once first if you want to see what agreements apply before agreeing. `--confirm` is a separate, explicit acknowledgment that this charges the account. Both are required; there's no lower-friction path, by design. Purchase needs an OAuth login (`gddy auth login`) — a bare PAT is rejected here even though PATs work fine for read commands.
+
+3. Purchase is async. The command waits briefly and reports status; if it's still pending, check back with `gddy domain operation status <operation-id>`. A completed purchase shows up in `gddy domain list`.
+
+Before quoting, contact info needs to exist: `gddy domain contacts init` writes a starter `contacts.toml` template (registrant/admin/billing/tech, all commented out) to the OS config directory. Any role left commented out falls back to the account default; any role you fill in needs all of its required fields (name, email, phone, full address).
+
+Always confirm with the user before running `purchase` — it's real money, and the action is not reversible.
+
+## Domain search and lookup
+
+```bash
+gddy domain suggest "coffee shop" --tlds com --tlds net --length-min 4 --length-max 15
+gddy domain available example.com --check-type fast   # or: full (live registry check, slower)
+gddy domain list --status ACTIVE
+gddy domain get example.com
+gddy domain agreements --tld com --privacy
+```
+
+Global `--limit <N>` caps result counts on list-like commands.
+
+## DNS management
+
+Valid record types: `A AAAA ALIAS CAA CNAME MX NS SOA SRV TXT`. `NS` and `SOA` are GoDaddy-managed and read-only — you can list them but not add/set/delete them.
+
+```bash
+gddy dns list example.com --type A
+gddy dns add example.com --type A --name www --data 192.0.2.1 --ttl 3600
+gddy dns set example.com --type TXT --name @ --data "v=spf1 -all"
+gddy dns delete example.com --type A --name www
+```
+
+`add` appends a new record; `set` replaces every record matching that type+name; `delete` removes every record matching that type+name. Type-specific requirements: `MX`/`SRV` need `--priority`; `SRV` also needs `--port`, `--weight`, `--protocol`, `--service`; `CAA` requires `--tag` (`--flag` is optional).
+
+`set` and `delete` are destructive — support `--dry-run` to preview the change and `--reason <text>` for an audit trail. Run with `--dry-run` first and show the user what would change before applying it for real.
+
+## Payments
+
+`gddy payments add` opens the browser to the account's payment-methods page — no card data is ever handled by the CLI itself. Purchases fail (403/422) without a valid payment method or Good-as-Gold balance on the account; check the error's `code` field, not just the HTTP status, to tell that apart from other failures.
+
+## Reference material
+
+Read these only when the task needs the detail — they're not needed for common domain/DNS operations:
+
+- `reference/api.md` — raw GoDaddy Domains API fallback (when `gddy` isn't installed/available, e.g. CI in a non-shell language): base URL/auth, the public OpenAPI specs to fetch and search directly, and the durable gotchas (idempotency keys on registration, the MCP server's read-only/no-auth scope).
+- `reference/errors-and-limits.md` — error envelope shape, retry/idempotency rules per HTTP method, and rate-limit headers/handling.

.agents/skills/gddy/reference/api.md

@@ -0,0 +1,19 @@
+# GoDaddy Domains API (raw HTTP fallback)
+
+Use this when the `gddy` CLI isn't installed or isn't a good fit for the task (CI pipelines, non-shell languages, etc.). When `gddy` is available, prefer it — it handles auth, quote-token bookkeeping, and idempotency for you. To install `gddy` itself, see the Setup section in SKILL.md.
+
+Base URL: `https://api.godaddy.com`
+
+Auth header: `Authorization: Bearer $GODADDY_PAT` (PAT generated from the Personal Access Token page under `https://developer.godaddy.com/docs/api-users/auth`). Legacy `sso-key key:secret` credentials still work for v1/v2 endpoints but not v3, and are deprecated — prefer a PAT for anything new.
+
+## Endpoint reference
+
+GoDaddy publishes machine-readable OpenAPI specs — fetch and search these directly instead of relying on hardcoded examples here, so this file doesn't need updating as the API grows:
+
+- Search, availability, registration (quote → register), DNS records: `https://developer.godaddy.com/openapi/domains-v3.json`
+- Domain listing, bulk availability, contacts, transfers, legacy purchase: `https://developer.godaddy.com/openapi/domains-v1.json`
+
+## Gotchas that won't change even as the API grows
+
+- **Registration is two calls, never one** — mirrors the CLI's `gddy domain quote` / `gddy domain purchase` split. Lock a quote first; it returns a single-use `quoteToken` valid for roughly 10 minutes. Execute the registration against that token with an `Idempotency-Key` header — required, not optional. Retrying with a *new* key can register (and charge for) the domain twice; always reuse the same key when retrying the same logical attempt.
+- **MCP server** (`https://api.godaddy.com/v1/domains/mcp`, streamable-http) is read-only and needs no authentication — public domain search/availability only, never registration, DNS, or anything account-specific. Full docs: `https://developer.godaddy.com/docs/api-users/mcp`.

.agents/skills/gddy/reference/errors-and-limits.md

@@ -0,0 +1,73 @@
+# Errors, retries, and rate limits
+
+## Error shape
+
+Every error response is a stable JSON envelope:
+
+```json
+{
+  "code": "INVALID_DOMAIN",
+  "message": "example is not a valid domain name",
+  "fields": [
+    { "path": "domain", "code": "INVALID_FORMAT", "message": "..." }
+  ]
+}
+```
+
+Always branch on `code`, never on `message` — message text can change between releases and isn't a stable contract. `fields` is present on validation errors (422) and points at which field(s) failed and why.
+
+429 (rate limited) responses add a `retryAfterSec` field and otherwise carry little useful body — read the headers instead (below).
+
+## Retry semantics — depends on the HTTP method, not just "is it safe to retry"
+
+| Operation | Idempotent? | Notes |
+|---|---|---|
+| Any `GET` | Yes | Always safe to retry. |
+| `POST /v1/domains/purchase` (and registration create) | **No** | Retrying without reusing an `Idempotency-Key` (v3) or otherwise confirming state first can double-purchase/double-charge. Check current state (e.g. does the domain already show up under the account) before retrying a failed purchase. |
+| `PUT` (e.g. DNS record replace / `gddy dns set`) | Yes | Safe to retry — it fully replaces state each time. |
+| `PATCH` (e.g. DNS record add / `gddy dns add`) | **No** | Appends; retrying a failed "add" can create duplicate records. Check current state before retrying. |
+| `DELETE` (e.g. `gddy dns delete`) | Yes | Safe to retry — deleting something already gone is a no-op. |
+
+## Rate limits
+
+60 requests/minute per credential, applied regardless of endpoint. Every response — not just 429s — carries these headers, so you can self-throttle before hitting the limit rather than reacting after:
+
+| Header | Meaning |
+|---|---|
+| `RateLimit-Limit` | Limit that applies to this request |
+| `RateLimit-Remaining` | Requests left in the current window |
+| `RateLimit-Reset` | Seconds until the window resets |
+
+On a 429, back off for at least `RateLimit-Reset` seconds (or the `retryAfterSec` field), plus some jitter if retrying programmatically in a loop.
+
+To stay under the limit in the first place:
+- Prefer bulk endpoints where they exist (e.g. `POST /v1/domains/available` for many domains at once, instead of looping single `check-availability` calls).
+- Use cursor pagination (`limit`/`marker`) sequentially rather than fanning out parallel page requests.
+- Don't share one credential across many independent callers and assume the limit is per-account — it's per-credential today, but that's an implementation detail, not a guarantee.
+
+If a legitimate use case needs a sustained rate above 60/min, that's a conversation with GoDaddy developer support, not something to work around client-side.
+
+## Common error codes (registration)
+
+These are the `code` values you'll actually see while quoting/registering a domain, with what each means:
+
+| `code` | Meaning | What to do |
+|---|---|---|
+| `DOMAIN_NOT_AVAILABLE` | Someone else registered the name first (race between check and purchase). | Re-check availability, suggest alternatives. |
+| `BILLING_DECLINED` | Payment method on file was charged and declined. | Surface to the user — they need to fix their payment method. |
+| `NO_PAYMENT_PROFILE` | No payment method on the account at all. | Direct the user to `gddy payments add` or the account's payment-methods page. |
+| `QUOTE_MISMATCH` | The `period` (or other term) at execute time doesn't match what was quoted. | Reuse the exact period from the quote, or fetch a fresh quote. |
+| `INVALID_AGREEMENT_KEYS` | `agreementTypes` sent don't match the TLD's `requiredAgreements` from the quote. | Use the exact keys the quote response returned, not guessed/remembered ones. |
+| `MISSING_CONTACT` | No registrant contact configured on the account. | Set up contacts (`gddy domain contacts init`, then fill in the file) before quoting. |
+| `MISSING_BILLING_PHONE` | Contact phone is missing or malformed. | Verify the contact has a complete, valid phone number. |
+
+## Common status codes and what to do
+
+- **400** — malformed request (bad JSON, missing required field shape). Fix the request; don't retry as-is.
+- **401** — missing/invalid/expired credential. Re-authenticate (`gddy auth login` or refresh the PAT) rather than retry.
+- **403** — authenticated but not authorized for this action (e.g. a PAT trying to purchase, which requires OAuth; or no payment method on file). Check `code` to distinguish "wrong credential type" from "account not payment-ready."
+- **404** — resource doesn't exist (domain not in the account, unknown operation ID). Don't retry.
+- **409** — conflict with current state (e.g. domain already has a pending operation). Check current state before retrying.
+- **422** — validation failure; see `fields` for which field(s) and why.
+- **429** — rate limited; see above.
+- **5xx** — server-side; safe to retry idempotent operations with backoff, not safe to retry non-idempotent ones (see table above) without first checking state.

.agents/skills/godaddy-cli/README.md

@@ -0,0 +1,30 @@
+# godaddy-cli skill
+
+Teaches an AI coding agent how to drive the `godaddy` CLI — applications, auth, environments, releases/deploys, extensions, and webhooks on the GoDaddy Developer Platform. It covers the JSON output contract, `next_actions` discovery, error codes, and the typical create/deploy/diagnose workflows, so the agent doesn't have to reverse-engineer any of that from `--help` output alone.
+
+See [SKILL.md](./SKILL.md) for the full instructions given to the agent.
+
+## Installation
+
+### Claude Code
+
+```bash
+claude plugin marketplace add godaddy/cli
+claude plugin install godaddy-cli@godaddy
+```
+
+This installs the plugin that bundles both skills in this repo (`godaddy-cli` and `gddy`); Claude picks whichever one fits the task automatically.
+
+### Any other AI coding agent
+
+This repo is also compatible with [skills](https://github.com/vercel-labs/skills), a package-manager-style installer for agent skills that isn't tied to Claude Code — it supports Cursor, Codex, Windsurf, opencode, and 70+ other agents in addition to Claude Code:
+
+```bash
+npx skills add godaddy/cli --skill godaddy-cli --agent claude-code
+```
+
+Swap `--agent claude-code` for whichever agent you use (`cursor`, `codex`, `windsurf`, `opencode`, ...). Run `npx skills add --help` for the full list of supported agents.
+
+## What it doesn't cover
+
+Domain search, registration, and DNS management live in a separate tool, `gddy`, with its own skill — see [../gddy/README.md](../gddy/README.md).

.agents/skills/godaddy-cli/SKILL.md

@@ -10,6 +10,8 @@ tags: [godaddy, cli, commerce, applications, deploy]
 
 The `godaddy` CLI is an agent-first tool. Every command returns a single JSON envelope to stdout. There is no plain text mode, no `--json` flag, and no table output. Parse stdout as JSON.
 
+GoDaddy also publishes `gddy`, a separate and newer CLI — a beta tool, distributed via GitHub Releases rather than npm, for domain search, registration, and DNS management. It's a different binary with its own install method, auth, and config; installing or using one doesn't affect the other. If the task is about domains or DNS records rather than applications, auth, environments, deployments, extensions, or webhooks, use the `gddy` skill instead of this one.
+
 ## Quick Start
 
 ```bash
@@ -64,7 +66,7 @@ Every command writes exactly one JSON object to stdout followed by a newline. Pa
 
 Check `ok` first. On failure, read `error.code` for programmatic handling and `fix` for the suggested recovery step.
 
-Error codes: `NOT_FOUND`, `AUTH_REQUIRED`, `VALIDATION_ERROR`, `NETWORK_ERROR`, `CONFIG_ERROR`, `SECURITY_BLOCKED`, `COMMAND_NOT_FOUND`, `UNSUPPORTED_OPTION`, `UNEXPECTED_ERROR`.
+Error codes: `NOT_FOUND`, `AUTH_REQUIRED`, `VALIDATION_ERROR`, `NETWORK_ERROR`, `CONFIG_ERROR`, `SECURITY_BLOCKED`, `COMMAND_NOT_FOUND`, `UNSUPPORTED_OPTION`, `UNEXPECTED_ERROR`, `FORBIDDEN`, `CONFLICT`, `RATE_LIMIT_EXCEEDED`.
 
 ### next_actions (HATEOAS)
 

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "godaddy",
+  "owner": {
+    "name": "GoDaddy",
+    "email": "opensource@godaddy.com"
+  },
+  "description": "Skills for using GoDaddy's command-line tools with an AI coding agent.",
+  "plugins": [
+    {
+      "name": "godaddy-cli",
+      "source": "./plugins/godaddy-cli",
+      "description": "Skill for using the GoDaddy CLI tools — the godaddy CLI (applications, auth, environments, deployments, extensions, webhooks) and the gddy CLI (domain search, registration, and DNS management).",
+      "author": {
+        "name": "GoDaddy"
+      }
+    }
+  ]
+}

README.md

@@ -4,6 +4,12 @@ Agent-first CLI for interacting with GoDaddy Developer Platform.
 
 ## Installation
 
+### Using an AI coding agent?
+
+Point your agent at this README and ask it to check for and install the relevant skill(s) — `godaddy-cli` for applications/auth/deploy/webhooks, `gddy` for domain search/registration/DNS. Once installed, the skill teaches the agent the CLI's JSON output contract and typical workflows, so it can drive the CLI correctly without guessing at flags. See [.agents/skills/godaddy-cli/README.md](./.agents/skills/godaddy-cli/README.md) and [.agents/skills/gddy/README.md](./.agents/skills/gddy/README.md) for one-line install commands (Claude Code and 70+ other agents).
+
+### Installing the CLI directly
+
 ```bash
 npm install -g @godaddy/cli
 godaddy --help