Domains DNS Agent Skill

Domains & DNS

You set up a name end to end: register or delegate it, write the records, and serve valid HTTPS. Almost every "my domain doesn't work" report is one of a handful of recurring mistakes. This skill names them and gives you paste-ready records plus the commands to prove they took.

Resolution order is debug order

A request resolves in one direction. Diagnose in the same direction, top-down, because the bug is almost always at the layer the user is *not* looking at.

• Name — does the domain exist and is it registered/not expired? (whois)
• Delegation — do the registrar's nameservers point at the DNS provider that actually holds the zone? (dig NS)
• Records — does the authoritative zone return the right A/AAAA/CNAME/ALIAS/MX/TXT/CAA? (dig @<authoritative-ns>)
• TLS — does the served chain validate and is it unexpired? (openssl s_client)

Rule: never debug TLS before you've confirmed the record resolves to the box you think it does — a cert error is often a record pointing at the wrong host. Query authoritative nameservers, not your laptop's cache, or you'll chase a stale answer for an hour.

Where the DNS lives

Pick one authoritative provider and keep the whole zone there. Splitting a zone across two providers (some records at the registrar, some at Cloudflare) is the source of "it works for me but not for them" — resolvers see whichever NS set answered.

| Host the zone at | Choose when | Why |

| --- | --- | --- |

| Registrar DNS (GoDaddy, Namecheap, Porkbull) | Tiny static site, one or two records | One vendor, fewer logins; weak APIs and slow propagation |

| Dedicated DNS (Cloudflare, DNSimple) | Most cases; want CNAME flattening + fast edits | Apex flattening, low TTL edits, good API; see ../cloudflare/SKILL.md |

| Cloud DNS (Route 53, Cloud DNS) | Already all-in on AWS/GCP and want alias-to-LB | Native alias records to cloud load balancers |

| Host-managed (Vercel, Netlify) | The host *is* the only thing the domain serves | Auto-TLS + apex flattening handled for you; see ../vercel/SKILL.md |

Apex vs www — the load-bearing trap

You cannot put a CNAME at the zone apex (the naked example.com). The spec forbids a CNAME coexisting with the SOA and NS records that must live there (RFC 1034 §3.6.2, RFC 2181). Registrars that let you save it produce a silently broken zone.

# Bad — CNAME at the apex. Breaks SOA/NS; mail and other apex records vanish.
example.com.        CNAME   cname.vercel-dns.com.

# Good — flatten at the apex (ALIAS/ANAME or provider flattening), CNAME only on the subdomain.
example.com.        ALIAS   cname.vercel-dns.com.     # Cloudflare/Netlify/Route53/DNSimple equivalent
www.example.com.    CNAME   cname.vercel-dns.com.

# Good (no flattening available) — hard-code the host's published A/AAAA at the apex.
example.com.        A       76.76.21.21
www.example.com.    CNAME   cname.vercel-dns.com.

Then pick one canonical host and 301 the other to it (apex→www or www→apex — either, just be consistent). Two live origins split your SEO and your cookies. The redirect lives at the host/edge, not in DNS.

Record cookbook (summary)

One example row per type. Edge cases — TXT 255-char chunking, MX priority math, the SPF 10-lookup limit, SRV format, NS/SOA, PTR, DNSSEC — live in references/record-cookbook.md.

| Type | Use for | Example (name → value) |

| --- | --- | --- |

| A | name → IPv4 | app → 76.76.21.21 |

| AAAA | name → IPv6 | app → 2606:4700::6810 |

| CNAME | subdomain → another name (never apex) | www → cname.vercel-dns.com. |

| ALIAS/ANAME | apex → another name (flattened to A/AAAA) | @ → cname.netlify.app. |

| MX | where mail is delivered (priority, lower = first) | @ → 10 mail.example.com. |

| TXT | SPF / DKIM / DMARC / domain-verification | @ → "v=spf1 include:_spf.google.com ~all" |

| CAA | which CA may issue certs | @ → 0 issue "letsencrypt.org" |

| SRV | service discovery (proto/port) | _sip._tcp → 10 5 5060 sip.example.com. |

The SPF/DKIM/DMARC/MX rows belong here. *Whether mail lands* — reputation, warmup, inbox placement — is ../email-deliverability/SKILL.md.

TLS / certificates

The 2026 reality: the CA/Browser Forum cut the maximum public-TLS lifetime to 200 days (from 398) on 2026-03-15, dropping to 100 days on 2027-03-15 and 47 days on 2029-03-15; domain-validation reuse is capped the same way (200 → 100 → 10 days). Manual annual certs are dead. Automate renewal or accept guaranteed outages.

Decision: how does the CA prove you control the domain?

| Challenge | Use when | Cost |

| --- | --- | --- |

| HTTP-01 | Single host, port 80 reachable, no wildcard | Simplest; needs inbound :80 |

| DNS-01 | Wildcard cert, or port 80 closed, or cert issued off-box | Needs API access to write a _acme-challenge TXT |

Rules, each with the failure it prevents:

• Add a CAA record that allows your CA *first*. 0 issue "letsencrypt.org". Wildcards need the separate issuewild tag. A CAA that omits your CA makes ACME fail with a CAA error before any cert is issued (RFC 8659).
• Serve the full chain, not the leaf. A leaf-only config validates in browsers (they cache intermediates) but fails on curl and mobile — the classic "works on my machine" TLS bug. Serve fullchain.pem.
• Use the ACME staging environment to test. Let's Encrypt allows 50 certs per registered domain per rolling 7 days; burning that on retries locks you out for a week. Renewals recognized via ARI (ACME Renewal Info) are exempt from the limit.
• Prefer platform-managed certs when the host offers them. Vercel/Netlify/Cloudflare provision and renew automatically once the record resolves — don't hand-roll certbot on top.

certbot/acme.sh recipes, wildcard via DNS-01, Cloudflare Full vs Full(strict), and the renewal-automation + ARI detail are in references/tls-and-acme.md.

Verify it

Query the authoritative answer and the wire, never your local cache.

dig +short app.example.com                      # the resolved record, your resolver's view
dig +trace example.com                          # full delegation chain from the root — spot stale NS
dig @ns1.provider.net example.com A             # ask the authoritative NS directly
dig CAA example.com +short                       # confirm the CA you use is allowed
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates  # served chain subject/issuer + validity window
curl -vI https://example.com 2>&1 | grep -Ei 'HTTP/|location|SSL certificate'  # status + redirect + cert verdict

Propagation is governed by TTL, not a fixed 48 hours (RFC 2181). To make a change land fast, lower the record's TTL (e.g. to 300s) *before* you change it, so resolvers re-query sooner. NS/registrar delegation changes can still lag because of registry/TLD TTLs.

scripts/verify.sh <domain> runs the whole done-check read-only: apex-CNAME check, CAA sanity, chain completeness + expiry, HTTPS reachability, www↔apex canonical. The full dig/openssl/curl playbook and an error → cause → fix table are in references/verify-and-debug.md.

Nameserver cutover (no downtime)

Order matters; each step has a reason.

• 24–48h ahead, lower the TTL on every record at the current provider (300s). Resolvers will pick up the new zone quickly when you flip.
• Pre-stage every record at the new provider — copy A/AAAA/CNAME/MX/TXT/CAA exactly. A missed MX row = lost mail the moment NS flips.
• Flip the NS records at the registrar to the new provider's nameservers. This is the only switch; the zone is already correct on the other side.
• Verify authoritatively with dig +trace and dig @<new-ns> until the new NS answer is global. Don't trust your browser.
• Once stable, raise TTLs back up (3600–86400s) to cut query load.

Anti-patterns

| Anti-pattern | Why it bites | Do instead |

| --- | --- | --- |

| CNAME at the apex | Illegal per spec; kills SOA/NS, MX, and other apex records | ALIAS/flattening or hard A/AAAA at apex |

| "Wait 48 hours" for propagation | Propagation is the TTL; you're just guessing | Lower TTL before change; verify with dig +trace |

| Confirming a change in your browser | Local/OS resolver cache lies for the old TTL | Query authoritative NS or @1.1.1.1 |

| Manual yearly cert renewal | Max lifetime is 200d now, 47d by 2029 — it *will* expire | ACME auto-renew or platform-managed TLS |

| Issuing certs with no CAA / wrong CAA | ACME fails with a CAA error before issuance | CAA 0 issue "<your-ca>"; add issuewild for wildcards |

| Serving the leaf cert only | Browsers cache intermediates; curl/mobile break | Serve fullchain.pem |

| Splitting one zone across two providers | Resolvers answer from whichever NS won; records vanish intermittently | One authoritative provider per zone |

| TTL left at 86400 during migration | Old answer cached for a day after you flip | Drop to 300s a day ahead |

| Testing certs against ACME production | Burns the 50-cert/7-day limit; week-long lockout | Use the staging endpoint first |