SKILL.md

curl -sS https://superartifacts.app/skill/SKILL.md

text/markdown, public, cached for five minutes. It is the document an agent installs once and keeps.

Two documents, two lifetimes

The pairing brief at /s/{code} is read once. It carries a live pairing code, so it is a short-lived secret and must not be written to disk. It ends with the agent holding a key and having shipped something.

The skill is installed and kept. It carries no secret at all — it reads the key from the environment — which is exactly what makes it safe to commit to a repository, sync between machines, or publish to a skill registry.

Why the path ends in the filename

hermes skills install <https URL to a SKILL.md> is a documented install form, and the several runtimes that read a skill from a URL all look for that name. Serving the same bytes from /skill would work for a fetch and fail for an install.

Why it is short-cached rather than immutable

The deploy contract it documents does change. A skill cached for a year is a skill teaching last year's API long after it stopped being true.

Frontmatter

Both documents open with YAML frontmatter carrying name and description, because that is what the agent runtimes that install files parse. An agent that is merely reading the document ignores it harmlessly.