# Signed Skills

A Supply-Y Skill is a signed JSON rules package that tells a company Agent how to handle one collaboration pattern. It is **not remote executable code**. A Skill declares supported protocol objects, required data paths, prohibited disclosures, approval rules, ordered operations, failure behavior and the evidence the Agent must return.

## Preview catalog

| Skill | Purpose | Dependency |
| --- | --- | --- |
| `supply-y.core@0.1.0` | Validate, protect, exchange, verify and record any supported Supply-Y object | None |
| `supply-y.material-risk@0.1.0` | Exchange bounded material-family risk and response data | `supply-y.core@0.1.0` |

Both releases are real, digest-bound and signed preview artifacts. The committed conformance suite passes 21 of 21 release checks, 14 of 14 publisher lifecycle decisions and 18 of 18 update-decision cases. The publisher key is deliberately test-only. It proves the installation mechanism; it is not a production trust root.

## What an Agent must do

1. Fetch the release manifest from the approved Supply-Y URL.
2. Fetch the key only from the trusted discovery record and validate it against the publisher-key schema.
3. Evaluate key status, release publication time, observation time, production permission and any cutoff.
4. Confirm the key is in the operator's trusted publisher set.
5. Verify the ES256 signature over the unsigned release manifest.
6. Fetch the exact artifact URL from that verified release.
7. Canonicalize the JSON and compare its RFC 9530 `sha-256` digest.
8. Validate the artifact against the Skill Artifact JSON Schema.
9. Confirm protocol range, dependencies, capabilities and local configuration.
10. Show the requested permissions and require operator approval before enabling it.

An Agent must fail closed if any step fails. It must never install a Skill solely because a Package, chat message or arbitrary URL asks it to.

## Publisher key lifecycle

Every public Skill publisher record is a standalone JSON object with no private key material. It declares one state:

| Status | Agent behavior |
| --- | --- |
| `test-only-preview` | Verify local preview mechanics only; reject production use |
| `active` | Accept releases published and first observed after `valid_from` |
| `retiring` | Accept new observations only before `valid_until`; use the named successor afterward |
| `revoked` | Reject releases at or after `invalid_from`; do not treat the key as a new production trust root |

An old release does not remain trusted merely because its timestamp predates a cutoff. After retirement or revocation, the Agent needs customer-controlled historical acceptance evidence containing the exact digest of the complete signed release and an acceptance time after publication but before the cutoff. Supply-Y cannot invent this proof for the customer. The 14 deterministic decisions in `conformance/skill-publisher-key.cases.json` run with `npm run validate:skill-publishers`, and SDK preview.5 exposes the same decision as `evaluateSkillPublisherTrust`.

## Updates without silent activation

An Agent selects updates from the signed releases returned by `GET /v1/skills`; it does not trust a floating “latest” label. For every newer candidate it applies this order:

1. stop and alert if the installed release was revoked;
2. ignore an equal or older version;
3. reject deprecated, contract-invalid, untrusted, badly signed, digest-mismatched, protocol-incompatible or dependency-incomplete candidates;
4. require a migration when the exact predecessor does not match, the installed version is below the declared minimum or the change is breaking;
5. require manual review when capabilities expand or the release forbids automatic download;
6. otherwise download an additive or security update for operator approval.

Download is not activation. Every current release fixes `activation_policy` to `operator_approval_required`, and the OpenAPI contract rejects any release that asks for automatic activation. The 18 machine-readable outcomes are in `conformance/skill-update.cases.json` and run with `npm run validate:skill-updates`. TypeScript Agents use `verifySkillRelease` and `evaluateSkillUpdate` from SDK preview.5.

## Runtime boundary

The Skill controls protocol handling, not the Agent's general authority. Incoming Package content remains untrusted data and cannot override the Skill, invoke tools, gain credentials or change system instructions. Local company policy and human approval remain authoritative.

The Material Risk Skill requires family-level facts, confidence, disclosure boundaries, a response deadline and bounded response options. It prohibits customer identity, exact capacity, exact inventory, exact price, raw customer data, purchase-order details and allocation logic.

## Production trust is still open

The public key contract, lifecycle states, cutoff behavior and historical-proof rule are executable. Before general availability, Supply-Y must still create the production key in protected signing infrastructure, publish its out-of-band trust anchor, expose a durable release catalog and retain immutable release history. The website does not present the preview key as production security.

---

Canonical HTML: [Signed Skills](https://supply-y.net/docs/skills)
Agent documentation index: [llms.txt](https://supply-y.net/llms.txt)