Skip to main content
skill CX Codex

agent-ready-personal-agent-protocol — Claude Code skill

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.

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-personal-agent-protocol -a claude-code
Open on GitHub

What agent-ready-personal-agent-protocol does

The skill serves discovery metadata for the Personal Agent Protocol in the .well-known directory of your domain and validates conformance to draft 0.1. The minimal configuration includes protocol version, organization name and domain, and a web object. The domain must match the hostname of the requested URL, ignoring a leading www..

For session-enabled interfaces, the skill declares agent.protocols with type and HTTPS endpoint, apis with type, URL, and description, or web.browser_session_endpoint. All require auth.issuer, which publishes RFC 8414 metadata: issuer matches auth.issuer exactly, poppy_domains contains organization.domain, and token_endpoint and revocation_endpoint are present. For issuer https://auth.example.com/tenant, metadata goes to https://auth.example.com/.well-known/oauth-authorization-server/tenant.

The check confirms public discovery and issuer binding, not working sessions or APIs. The draft may change before version 1.0. Scan results appear in checks.discovery.personalAgentProtocol, with details.issuerValidation reporting verified, notRequired, unverified, invalid, or notChecked.

What it helps with

  • publish Personal Agent Protocol discovery metadata on your domain
  • validate OAuth issuer binding to organization domain
  • declare available agent interfaces and APIs with endpoints

Example prompts for the agent

  • Place Poppy discovery metadata at /.well-known/poppy.json with your organization details.
  • Validate issuer metadata for the auth.issuer in your configuration.
  • Add agent.protocols and apis declarations for implemented interfaces.

How to install agent-ready-personal-agent-protocol

1Skills CLI (Vercel)

npx skills add fabricioctelles/skills --skill agent-ready-personal-agent-protocol -a claude-code

2Manually: put the files in place

~/.claude/skills/personal-agent-protocol/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/personal-agent-protocol/

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

Questions about agent-ready-personal-agent-protocol

How to install agent-ready-personal-agent-protocol in Claude Code?

Run npx skills add fabricioctelles/skills --skill personal-agent-protocol -a claude-code, the skill file will be in ~/.claude/skills/personal-agent-protocol/SKILL.md.

What does agent-ready-personal-agent-protocol do?

Publishes Personal Agent Protocol draft 0.1 discovery metadata at /.well-known/poppy.json and validates OAuth issuer binding to the organization domain. This is an informational check that does not affect readiness levels.

What should poppy.json contain for minimal configuration?

Protocol version 0.1, an organization object with name and domain, and a web object. The domain must match the hostname of the requested URL, ignoring www.. Serve JSON, not your SPA's HTML fallback.

Source text

SKILL.md · Apache-2.0
---
name: agent-ready-personal-agent-protocol
description: >
  Sub-skill: Implement Personal Agent Protocol (Poppy) discovery. Publish
  /.well-known/poppy.json (draft 0.1) and validate its OAuth issuer binding.
  Informational check; does not affect level or score.
---
# Implement Personal Agent Protocol (Poppy) discovery

Publish public discovery metadata for the [Personal Agent Protocol draft
0.1](https://personalagentprotocol.org/docs/spec#3-discovery). This check is
informational and does not affect readiness levels or percentage scores.

## Website-only discovery

Serve JSON at `https://YOUR-DOMAIN/.well-known/poppy.json`:

```json
{
  "protocol_version": "0.1",
  "organization": { "name": "Example Company", "domain": "example.com" },
  "web": {}
}
```

Replace the example organization with your actual name and domain. The domain
must match the hostname of the requested well-known URL, ignoring leading
`www.`. HTTPS redirects to a hosting provider are allowed, but that provider's
hostname must not replace your organization domain. Return JSON, not your SPA's
HTML fallback. Unknown fields and optional extensions are allowed.

## Session-enabled interfaces

Declare the interfaces you actually implement: `agent.protocols` entries with
`type` and HTTPS `endpoint`, `apis` entries with `type`, HTTPS `url`, and
`description`, or `web.browser_session_endpoint`. Agent/API declarations and
browser-session endpoints require `auth.issuer`.

The issuer must publish RFC 8414 metadata with:

- `issuer` exactly matching `auth.issuer`;
- `poppy_domains` containing `organization.domain`;
- HTTPS `token_endpoint` and `revocation_endpoint`;
- `authorization_endpoint` when `auth.direct` is declared;
- `device_authorization_endpoint` when `auth.device` is declared.

For issuer `https://auth.example.com/tenant`, publish metadata at
`https://auth.example.com/.well-known/oauth-authorization-server/tenant`.
Direct, device, and mediated sign-in declarations contain scope arrays. Mediated
sign-in also describes its endpoint and credential fields; never put actual
credentials or secrets in discovery metadata.

Publish only capabilities backed by working implementations. Passing this check
confirms public discovery and issuer binding, not functioning sessions, sign-in,
API authorization, or conversations. The draft may change before version 1.0.

## Verify

Scan your site and inspect `checks.discovery.personalAgentProtocol`. Its
`details.issuerValidation` reports `verified`, `notRequired`, `unverified`,
`invalid`, or `notChecked`. Use the audit evidence to diagnose invalid fields,
redirects, and issuer/domain mismatches. Network failures and unsupported major
versions return `unableToCheck` while retaining available discovery evidence.

© fabricioctelles · Apache-2.0 · fabricioctelles/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set46

The whole set →
agent-ready-webmcp agent-ready-webmcp wires a site's actions into the WebMCP API so browser-based AI agents can find and call them. CX Codex +1 ★ 141repo stars 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-auth-md 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. 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

Project sponsors

Companies that keep this analytics open