Agent Skill for SSL and Certificates

Certificate faults have a small number of causes and a large number of confusing symptoms. The same underlying problem shows up as a browser warning for one person, a curl failure for another, and a working site for a third. That gap between symptom and cause is exactly what a skill is good for.

What it depends on

Reading a live certificate means completing a TLS handshake, which instructions cannot do. The check comes from an MCP server:

claude mcp add --transport http toolhq https://toolhq.io/api/mcp

That provides ssl_check and dns_lookup, which is what the skill below calls.

The skill

Save as .claude/skills/tls-triage/SKILL.md:

---
name: tls-triage
description: Diagnose TLS and certificate faults on a live host, including
  expiry, incomplete chains, hostname mismatches, untrusted roots and
  key mismatches. Use when a site shows a certificate warning, a client
  reports an expired or untrusted certificate, curl or a mail client
  fails where a browser works, or someone asks whether a chain is
  complete.
---

# TLS triage

Run `ssl_check` first and work from what it returns. Never state an
expiry date, issuer or chain contents from memory.

If the service is not on 443, pass the port explicitly. Mail submission
on 587 and management ports on 8443 are common and easy to forget.

## The rule that prevents most wrong answers

**A working browser is not evidence that the chain is complete.**

Browsers cache intermediate certificates from other sites they have
visited, and will often complete a chain the server failed to send. So
the same host can work in Chrome and fail in curl, Java, Python, Go and
every mail client, which is the single most reported and most
misdiagnosed TLS symptom there is.

When someone says "it works in my browser", treat that as unverified
and run the check.

## Order of investigation

### 1. Expiry
The most common cause and the quickest to confirm. Report the exact
date. If it expires within thirty days, say so even when it is not the
present fault.

### 2. Chain completeness
The most commonly misdiagnosed cause. The server must send the leaf
first, then every intermediate up to, but not including, a trusted
root. Sending the root is harmless but pointless; omitting an
intermediate breaks every client without a cached copy.

If an intermediate is missing, the fix is a server configuration
change, not a reissue. Do not tell the user to buy or regenerate a
certificate for a chain fault.

### 3. Hostname match
The requested name must appear in the subject alternative names. The
common name alone is no longer sufficient for modern clients.

Wildcards cover exactly one label: `*.example.com` matches
`www.example.com` and does not match `a.b.example.com` or bare
`example.com`.

### 4. Trust
A chain that is complete and unexpired but still untrusted means the
root is absent from that client's trust store. Internal CAs and self
signed certificates land here. The fix is distributing the root, not
changing the server.

### 5. Key and certificate agreement
If the server refuses to start or serves the wrong certificate, the
private key may not match. Compare the public key moduli rather than
guessing from filenames.

## Report back

1. The cause, in one sentence.
2. The evidence from the check: dates, issuer, the chain as served.
3. The fix, as the specific change to make, and on which side.
4. Anything you could not verify.

Why these five, in this order

The sequence is not arbitrary. It runs cheapest and most likely first, and it puts the two causes that get confused next to each other.

Expiry is first because it is unambiguous and ends the investigation when true. Chain completeness is second because it is the cause people reach for last and should reach for second. Hostname and trust come after, because both are frequently consequences of a misread of the first two. Key mismatch is last because it presents differently: the service usually will not start at all.

The browser caching trap, in more detail

This deserves the space because it costs so much time.

A certificate chain is assembled by the client. The server sends what it has, the client fills gaps from what it already trusts or has cached, and the chain either reaches a trusted root or it does not. Browsers are generous: they cache intermediates they have seen elsewhere, and some will fetch a missing one from the URL in the certificate's authority information access extension.

Almost nothing else does this. curl, Java, Python requests, Go's standard library and most mail servers use exactly what the server sent.

So a misconfigured server looks fine in the one place a developer checks first, and broken everywhere that matters. An assistant with general TLS knowledge will not warn you about this, because it is an implementation detail rather than a fact about the protocol. Writing it into the skill is the whole value of having a skill.

You can confirm which intermediates a host actually sends, and get a corrected bundle, in the SSL chain fixer.

Checking the assistant's conclusions

Run the same host through an exact tool for the first few cases:

What the server sends, and a corrected fullchain: SSL chain fixer
Expiry, issuer and names: SSL checker
Decode a PEM you have on disk: SSL decoder
Does this key match this certificate: key matcher
Does this certificate match this CA bundle: CA matcher
Revocation status: OCSP checker
What has been issued for a domain: CT log lookup
Many hosts at once: bulk SSL checker

Extending it

The natural sibling files, loaded only when the job turns out to need them:

tls-triage/
  SKILL.md
  chain-order.md    assembling a fullchain for nginx, apache and haproxy
  trust-stores.md   which roots each client population trusts
  renewal.md        your own renewal process and who owns it

That third one is where a skill stops being generic. Nobody else can write down that your certificates come from an internal CA, renew on a particular schedule, and that the load balancer needs a reload rather than a restart. Those are the lines that make the skill worth keeping.

For the background on why chain errors happen in the first place, see fixing SSL certificate chain errors. To build the skill itself from scratch, how to write your first agent skill uses this same example line by line.

SSL Chain Fixer — Find a missing intermediate certificate and get a corrected fullchain.pem for your server.