skill_index in poppy.json: How Agent Skills Work, Step by Step

On 2 November 2026, draft 0.3 of the Personal Agent Protocol gained a new optional field in poppy.json: skill_index. With it, a company can publish skills, written notes that tell a personal agent how to do a task there, such as "change a booking", step by step.

We added skills to our three test stores and taught our test agent to use them the same day, then ran real tasks against both. This post shows what skill_index is, how an agent finds, checks and uses a skill, what happens when a skill fails its check, and what a skill can't do. One thing first: draft 0.3 isn't final, so any of this can still change.

#What is skill_index?

skill_index is an optional list in a company's poppy.json of the skills it publishes for personal agents acting for a person at that company. It's defined in section 9.4 of the draft 0.3 specification, "Agent context".

A company's APIs say which operations exist. A skill says how to combine them into a task: what you need first, the order of the calls, and what to do with the common results. The spec's own example is "changing a booking through the Company's APIs".

The protocol doesn't invent its own format for this. skill_index embeds an index in the format of the Agent Skills discovery proposal, pinned to one revision, and each skill is a SKILL.md file in the Agent Skills format. The spec notes that the proposal is a draft, not an adopted standard.

Skills are optional on both sides. A company doesn't need to publish them to support the protocol, and an agent may ignore them and use the company's APIs directly.

#What it looks like in poppy.json

Here is the skill_index from one of our test stores, Northlight Flowers, shortened to one skill:

"skill_index": {
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "change-flower-delivery",
      "description": "Change a booked flower delivery at Northlight Flowers for the User. Move it to another date, swap, add or remove bouquets, or add or change the card message.",
      "type": "skill-md",
      "url": "https://flowers.papsandbox.com/.well-known/agent-skills/change-flower-delivery/SKILL.md",
      "digest": "sha256:15c64eb5593a5e04984eb0d3fb7da412818f8ea70ccc6551beaafb92e2be1fd6"
    }
  ]
}

Every entry has five fields:

Field	What it is
name	The skill's name. It should match the name in the skill's own file.
description	What the skill does and when to use it. The agent picks a skill from this.
type	skill-md for a single SKILL.md file, or archive for a skill with supporting files.
url	Where to fetch it. Relative, path-only and full URLs on other domains are all allowed.
digest	The SHA-256 of the file's exact bytes, written sha256: plus 64 lowercase hex characters.

The $schema value tells the agent which version of the index format it's reading. It's an identifier, not a link the agent needs to fetch.

#What a skill looks like

A skill is a markdown file with a short header. This is the start of Northlight Flowers' change-flower-delivery:

---
name: change-flower-delivery
description: Change a booked flower delivery at Northlight Flowers for the User. Move it to another date, swap, add or remove bouquets, or add or change the card message. Use when the User asks to change, move or reschedule a flower order or its card.
---

# Change a flower delivery

This skill is the store's guidance. It grants no account access, changes no scopes and gives no
approval. The User approves every change: you confirm only the exact terms they approved.

## Before you start

- You need a signed-in Session with both scopes:
  - `orders:read` to read the User's orders (`my_orders`).
  - `orders:write` to propose and confirm a change (`change_order`, then confirm).

## Steps

1. **Find the order.** `my_orders` (`GET /poppy/orders`).
2. **Pick the new terms.** A new date: `delivery_dates` (`GET /poppy/delivery-dates`).
3. **Propose the change.** `change_order` (`POST /poppy/orders/{order_id}/changes`).
4. **Ask the User.** Show them the operation's `summary`, the `price_difference` and `new_total`.
5. **Confirm only what they approved.**

The full file goes on to cover the errors the store returns and what to do with each. Nothing in it is new to the protocol: every tool, path and scope it names is already in the store's poppy.json and API description. What the skill adds is the order and the advice.

A store's For agents page can list its skills too. Our test stores show them next to the sign-in types, APIs and excluded tasks:

#The runs behind this post

On 3 November we gave PAP Playground, a test personal agent, tasks at PAP Sandbox test stores that speak draft 0.3 as it stood on 2 November:

• Northlight Flowers: "Move my flower delivery to Saturday and add a card saying Happy birthday Mum."
• Northlight Flowers, signed out: "What bouquets can you deliver this Friday?"
• A copy of Northlight Flowers whose index lists the wrong digest for one skill, with the first task.

The agent ran on Gemini 3.6 Flash. I maintain PAP Playground, PAP Sandbox and PAP Checker. These are test stores with a test customer and no real orders: nothing is charged and nothing ships.

#Step by step: how an agent uses a skill

#1. It reads the index with the rest of poppy.json

The agent reads poppy.json as it always does. The trace shows one extra line for skill_index: three skills, change-flower-delivery, check-flower-order and find-flowers.

The agent is shown only each skill's name and description at this point, not the contents. The spec describes it this way: the agent can "identify relevant skills from their descriptions before fetching their contents".

#2. It picks the skill that fits the task

For "Move my flower delivery to Saturday", the agent chose change-flower-delivery from its description and loaded it before making any other call. For the signed-out question about Friday, it chose find-flowers.

#3. It fetches the file and checks the digest

The agent fetched the SKILL.md and hashed the bytes it received. The result matched the index, so it used the skill:

The fetch carried no sign-in token, Session header or cookie. That's deliberate: the spec says listing a skill on another domain "does not make that domain an API endpoint or authorize sending it credentials or Session headers". A skill host only serves files.

#4. It does the task through the company's own channels

With the skill loaded, the agent did the task the usual way, in the order the skill describes:

1. It asked for the person's orders. The store answered insufficient_scope, so the person signed in on Northlight Flowers' own page and allowed "See your orders".
2. It read the open delivery dates and proposed the change. The store answered insufficient_scope again, because changing an order needs orders:write, so the person signed in a second time and allowed "Change your orders".
3. The store answered approval_required with the exact terms, and the agent showed them to the person:

4. The person approved. The agent sent the same request again with that approval, and the store performed the change once.

The agent's reply: "I have moved your delivery for order NF-7OI7ZLZJ (Spring Tulips) to Saturday, 7 November 2026, and added a gift card with the message "Happy birthday Mum". Adding the gift card envelope ($3.00) brings your new total to $33.00."

The skill didn't sign anyone in or approve anything. The two sign-ins and the approval are the same steps the task needs without a skill. What the skill gave the agent was the route: which calls, in which order, and what each answer means.

One detail across our runs: when to load a skill is up to the agent. In this run it loaded the skill before its first call. In an earlier test with a different model, the agent loaded it in the same turn as its first two calls, so the skill could only shape the steps after them. An agent that reads a skill before acting gets more from it.

#Who pays the extra $3?

The change added a card, so the order went up by $3.00. The person approved that amount, and the store performed the change. But nothing in the run pays the $3.00: the terms say it's "charged to the card used for the order", and in our test store nothing is charged.

That's on purpose. The draft's Path to 1.0 lists payments as an open topic: "how a personal agent makes payments in a way that fits the protocol". The Operations extension's own example charges the difference "to the card used for the order" too, so today a company collects it with whatever it already holds. That works for a small change to an existing order. It doesn't cover a first purchase, a new card, or a company that wants proof the person approved rather than the agent's word for it. Signed approvals are on the same open-topics list, and an open proposal for a payments extension would bind a payment credential to one operation, one amount and one expiry. Neither is in the draft yet.

#When a skill fails its check

The third run used a copy of the same store, Northlight Flowers (stale skill test), whose index lists the wrong digest for change-flower-delivery. The file it serves is the same one; only the published digest is different.

The agent fetched the file, hashed it and got sha256:15c64eb5… where the index said sha256:fd87c0f3…. It refused the skill, did the task with the store's ordinary tools, through the same two sign-ins and the same approval, and told the person:

"Please note that the store's guidance skill for changing flower deliveries could not be loaded because its content did not match the store's published digest, so I proceeded using the standard store tools instead."

That's what the rules ask for. The Agent Skills proposal says a mismatch "indicates the content is corrupted or tampered with" and clients "must not use unverified content". The protocol's guides add that when an agent skips a company's skill, it should tell the person "if it matters for the task, so they know the company's guidance wasn't used".

A mismatch is most likely to mean a company edited a skill and forgot to update the digest. The check can't tell an honest mistake from tampering, so it treats both the same way.

#What a skill can't do

The spec is plain about a skill's authority. A skill is the company's own content, and:

• it grants no account access and changes no OAuth scopes
• it supplies no approval from the person
• it doesn't authorize any other task or override the agent's own rules
• an agent must not run scripts from a skill unless the person or the agent's settings explicitly allow it

The spec also lists skill indexes and skill contents among the things an agent reads that come from the company, not from the person. In practice that means an agent should treat a skill as advice about the company's tools, not as instructions. Our test agent wraps every skill it loads in a label that says so before the model sees it.

The digest only proves that the file is the one the company published. It doesn't prove the advice is right, current or in the person's interest. That judgment stays with the agent and the person.

#The separate index at /.well-known/agent-skills/index.json

A company can also publish the same index at /.well-known/agent-skills/index.json, the address the Agent Skills proposal defines, for agents and tools that don't read poppy.json. The protocol makes this optional and doesn't require those other tools to look for poppy.json.

If you publish both, full URLs let the two copies list identical entries. Relative URLs resolve against the document they're in: against the final poppy.json URL after redirects in one case, and against the index URL in the other.

#What we see today

As of 3 November, none of the 31 sites on our list of sites publishing poppy.json include skill_index yet. That's expected: the field is a day old.

Five of those sites already publish skills at /.well-known/agent-skills/index.json, so moving the same entries into poppy.json is a small step for them. They include Ticket Fairy, whose skills cover whole workflows such as finding event tickets and setting up as an organiser, and GT Slot Cars, a shop that publishes skills for product search and managing a cart.

#What it means for a company that publishes poppy.json

• Start with the tasks people ask for most. A skill earns its place when a task takes several calls in a set order, like changing an order with an approval step. A skill that restates one API call adds little.
• Name only what you offer. Every tool, path and scope in a skill should already be in your poppy.json and API description.
• Update the digest whenever you edit a skill. An agent will refuse a skill whose bytes don't match. Computing the digest from the served file, at build or serve time, means it can't drift.
• Say what the skill can't do. Our skills open with a line saying they grant no access or approval, which matches the spec and helps the model reading it.
• Check the file before you publish. The official kit validator checks skill_index against its schema, and our validator checks the rest of poppy.json.

#What it means for agent builders

• Read the names and descriptions first, and fetch a skill only when it matches the person's task.
• Verify the digest before the model sees a word of the file. On a mismatch, carry on without it, and tell the person if it matters.
• Send nothing to skill hosts but the request for the file: no tokens, no Session header, no cookies.
• Wrap skills as company content. Never let one grant access, approve a change or run a script.
• Load the skill before the first call that matters, not alongside it.

#What's still open

• The Agent Skills discovery proposal is a draft, and the protocol pins one revision of it. A new revision would need a spec change.
• Our runs used skill-md skills only. archive skills bundle supporting files, which brings the proposal's archive safety rules into play: no path traversal, no links outside the skill, and a cap on unpacked size.
• How cache headers on skills should combine with the digest, beyond "the same digest means the same file", is left to each agent.

#FAQ

#What is skill_index in poppy.json?

An optional list of skills a company publishes for personal agents: written guides to doing a task at that company with its APIs. It's defined in section 9.4 of the Personal Agent Protocol draft 0.3.

#Do I need to publish skills to support the Personal Agent Protocol?

No. Skills are optional for companies, and agents may ignore them and use your APIs directly.

#What format do skills use?

Each skill is a SKILL.md file in the Agent Skills format, and the index follows the Agent Skills discovery proposal (schema 0.2.0), embedded in poppy.json.

#Can a skill give an agent access to my account?

No. A skill grants no account access, changes no scopes and supplies no approval. Sign-in and your approval of each change still apply.

#What happens if a skill's digest doesn't match?

The agent must not use it. In our run, the agent did the task with the store's ordinary tools instead and told the person the store's guidance wasn't used.

#Is skill_index the same as /.well-known/agent-skills/index.json?

It's the same index format. skill_index embeds it in poppy.json; the well-known file is a separate copy a company may also publish for other tools.

#Is draft 0.3 final?

No. Draft 0.3 is in progress, so skill_index and its rules can still change before it's published.

#Sources

• Personal Agent Protocol specification, draft 0.3, section 9.4 "Agent context", in progress (read 3 November 2026)
• Changelog, "Skills for Personal Agents", personalagentprotocol.org (read 3 November 2026)
• Guides, draft 0.3, personalagentprotocol.org (read 3 November 2026)
• Agent Skills discovery proposal, the revision draft 0.3 pins, draft
• Agent Skills format, agentskills.io
• Path to 1.0, open topics, personalagentprotocol.org (read 3 November 2026)
• Operations extension, draft 0.3, personalagentprotocol.org
• Proposal: payments extension (#61), open
• Test runs on PAP Playground against PAP Sandbox test stores, 3 November 2026