Skip to main content
skill CX Codex

agent-ready-auth-md — Claude Code skill: what it does, how to install

agent-ready-auth-md publishes an auth.md file and OAuth metadata so agents can discover how to register with a service. Kicks in when a scanner flags the authMd check as failing.

Apache-2.0 ★ 141 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add fabricioctelles/skills --skill agent-ready-auth-md -a claude-code
Open on GitHub

What agent-ready-auth-md does

The skill places /auth.md at the service root as a Markdown file with an H1 heading mentioning “auth.md”. Alongside it, the OAuth Protected Resource document carries resource, authorization_servers, scopes_supported and bearer_methods_supported set to header, while each listed authorization server gets its own metadata with a matching issuer value.

When Authorization Server metadata is present, the skill adds an agent_auth block with skill, register_uri and at least one full registration method. Three flows get separate field sets: ID-JAG, verified email and anonymous access, each with its own assertion types, credential types and either a claim_uri or a revocation_uri.

The skill blocks calling POST /agent/auth during passive scans, since that request can create an account, send an email or issue a credential — the public discovery documents are meant to stay the safe source of truth.

What it helps with

  • publish auth.md with OAuth metadata for agents
  • pass the authMd check in an agent-ready scanner
  • document an agent registration endpoint without a live auth server
  • set up Protected Resource and Authorization Server metadata
  • add an agent_auth block with an ID-JAG or verified-email registration method

Example prompts for the agent

  • Add auth.md so the authMd check passes
  • Write OAuth Protected Resource metadata in auth.md for our API
  • Set up an agent_auth block with a verified-email registration method

How to install agent-ready-auth-md

1Skills CLI (Vercel)

npx skills add fabricioctelles/skills --skill agent-ready-auth-md -a claude-code

2Manually: put the files in place

~/.claude/skills/auth-md/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/auth-md/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-ready-auth-md

How do I install agent-ready-auth-md in Claude Code?

Run npx skills add fabricioctelles/skills --skill auth-md -a claude-code; the skill lands at ~/.claude/skills/auth-md/SKILL.md.

What does agent-ready-auth-md do?

It helps a service publish an auth.md document with OAuth metadata so agents can find a way to register. It's used when a scanner's authMd check fails.

What does Authorization Server metadata need to include?

It needs a valid issuer field that matches the issuer advertised in the Protected Resource metadata, or the check won't pass.

Source text

SKILL.md · Apache-2.0
---
name: agent-ready-auth-md
description: >
  Sub-skill: Implement Auth.md for agent registration discovery. Serve /auth.md with OAuth
  metadata at /.well-known/oauth-protected-resource and authorization server endpoints.
---
# Skill: Implement Auth.md Agent Registration Discovery

## What This Skill Does

Helps a service publish Auth.md support for agent registration. Use this when a scanner reports the `authMd` check is failing or when adding the Auth.md standard to an API or application.

## Requirements

- Serve `/auth.md` from the service root as Markdown with an H1 heading that contains `auth.md` (for example, `# auth.md` or `# Example auth.md`).
- Prefer publishing OAuth Protected Resource Metadata at `/.well-known/oauth-protected-resource` for the resource server.
- Include `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported` with `header` in the PRM document.
- Publish OAuth Authorization Server metadata at each advertised authorization server's `/.well-known/oauth-authorization-server` URL.
- Include a valid `issuer` in Authorization Server metadata and ensure it matches the issuer advertised in PRM.
- Add an `agent_auth` block with `skill`, `register_uri`, and at least one complete registration method when Authorization Server metadata is available.
- If OAuth metadata is not available, keep `/auth.md` self-contained: identify the agent audience, document registration or provisioning endpoint(s), list supported method(s), and explain credential use.

## Flow Metadata

- **ID-JAG**: include `identity_types_supported: ["identity_assertion"]`, `identity_assertion.assertion_types_supported` with `urn:ietf:params:oauth:token-type:id-jag`, and credential types. Include `revocation_uri` and the revocation event in `events_supported` when supported; scanners may warn when they are omitted, but they are not required for detection.
- **Verified email**: include `identity_assertion.assertion_types_supported` with `verified_email`, credential types, and `claim_uri`.
- **Anonymous**: include `identity_types_supported: ["anonymous"]`, `anonymous.credential_types_supported`, and `claim_uri`.

## Notes

Do not probe `POST /agent/auth` during passive scans. Registration can create accounts, send email, or issue credentials. Public discovery documents are the safe source of truth.

## Validate

```http
POST https://isitagentready.com/api/scan
Content-Type: application/json

{"url": "https://YOUR-SITE.com"}
```

Check that `checks.discovery.authMd.status` is `"pass"`.

## References

- [Auth.md Specification](https://auth-md.com)
- [RFC 9728 — OAuth Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728)
- [RFC 8414 — OAuth Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414)

© fabricioctelles · Apache-2.0 · fabricioctelles/skills

Similar skills

All skills for Security →

From the same set46

The whole set →
agent-ready-ai-rules agent-ready-ai-rules is a skill that adds RFC 9309 rules for AI search and training crawlers to robots.txt, controlling page visibility in AI answers and use for model training. CX Codex +1 ★ 141repo stars agent-ready-mpp agent-ready-mpp teaches AI agents to configure Machine Payment Protocol (MPP) discovery in OpenAPI schemas by adding x-payment-info tags to payable endpoints. CX Codex +1 ★ 141repo stars agent-ready-dns-aid The agent-ready-dns-aid skill guides DNS-AID records that let agents locate endpoints through DNS. Use it when publishing SVCB or HTTPS records under _agents. CX Codex +1 ★ 141repo stars agent-ready-personal-agent-protocol agent-ready-personal-agent-protocol publishes Personal Agent Protocol (Poppy) draft 0.1 discovery metadata at /.well-known/poppy.json and validates OAuth issuer binding. CX Codex +1 ★ 141repo stars agent-ready-ard The agent-ready-ard skill guides you through publishing /.well-known/ai-catalog.json so agents can discover MCP servers, A2A agents, skills, and API tools. Use it to add resource discovery to a project. CX Codex +1 ★ 141repo stars agent-ready-scan-site agent-ready-scan-site scans a website and validates compliance with AI agent standards. Evaluates 23 checks across five categories: discoverability, content accessibility, bot rules, API/auth discovery, and commerce. CX Codex +1 ★ 141repo stars ultimate-design-system-master ultimate-design-system-master guides users through an 18-step briefing questionnaire to produce design systems, brand assets, and UI code across 10 specialized generators. CX Codex +1 ★ 141repo stars substack-expert substack-expert — a skill for shaping Substack newsletters, from post structure and SEO fields to reader engagement and free-to-paid conversion. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open