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
npx skills add fabricioctelles/skills --skill agent-ready-personal-agent-protocol -a claude-codeWhat 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.jsonwith your organization details. - Validate issuer metadata for the
auth.issuerin your configuration. - Add
agent.protocolsandapisdeclarations 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-code2Manually: put the files in place
~/.claude/skills/personal-agent-protocol/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/personal-agent-protocol/
1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill agent-ready-personal-agent-protocol -a codex2Manually: put the files in place
.agents/skills/personal-agent-protocol/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill agent-ready-personal-agent-protocol -a cursor2Manually: put the files in place
.cursor/skills/personal-agent-protocol/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fabricioctelles/skills skills/agent-ready-cloudflare/personal-agent-protocol2Manually: put the files in place
.github/skills/personal-agent-protocol/SKILL.md1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill agent-ready-personal-agent-protocol -a gemini-cli2Platform CLI
gemini skills install https://github.com/fabricioctelles/skills --path skills/agent-ready-cloudflare/personal-agent-protocolManually: put the files in place
.devin/skills/personal-agent-protocol/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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