skills-visibility

Skills visibility

Contract

Inputs

• Skill source directory (required): a directory tree where each skill lives at skills/<name>/SKILL.md, optionally with sibling files. Must be a Git repo if repo-based install methods are used.
• Publisher-controlled https origin (required): the https:// origin the publisher controls and serves from (e.g., https://yourdomain.com). Never raw.githubusercontent.com or any host whose delivery the publisher does not control.
• Local output directory (required): local path where the publishable tree is written. The publisher copies or deploys this tree to their domain.
• Optional bundle slug: if publishing a bundle of multiple skills as one combined archive, the bundle slug. Each contained skill still gets its own index entry.

Procedure

1. Classify each skill as single-file, multi-file, or bundle container and fail on duplicate names. For every skills/<name>/ directory: if it contains only SKILL.md, shape is single-file. If it contains SKILL.md plus sibling files (references, scripts, assets), shape is multi-file. If it contains nested skills/ subdirectories, shape is bundle container. Check every name for uniqueness across the entire source tree. A duplicate shadows rather than adds; abort before writing the index. Done when: every skill is classified and no duplicate names are found.
2. Build deterministic flat artifacts. For each skill, produce the artifact its shape requires in the output directory under agent-skills/:
   • Single-file: copy SKILL.md as-is to agent-skills/<name>/SKILL.md.
   • Multi-file: create a reproducible tar with sorted entries, zeroed owner, and fixed mtime (tar --sort=name --owner=0 --group=0 --mtime=@0 -cf agent-skills/<name>.tar.gz -C <skill-dir> .). Verify tar -tzf shows no wrapping folder.
   • Bundle container: create a reproducible tar of the entire bundle directory with the same deterministic flags. Done when: every artifact is produced as a flat deterministic archive or copied file.
3. Write .well-known/agent-skills/index.json with the exact schema and sha256 digests computed from the exact artifact bytes. The document has exactly two top-level keys: $schema and skills[]. Per-skill fields: name (lowercase letters, digits, single dashes, unique), description (from frontmatter), type (skill-md for single-file, archive for multi-file or bundle), url (pointing at the publisher-controlled domain), and digest (sha256:<hex> computed over the exact bytes of the produced artifact). Hash in the same pass that builds the artifact, never from a separate copy. Done when: the index is written with every digest matching its produced bytes and conforming to the schema.
4. Generate at least two install methods per skill. Produce pnpm dlx skills add https://<domain>/agent-skills --skill <name> -a <agent> -g plus a curl fallback (curl -sL https://<domain>/agent-skills/<name>/SKILL.md). When a Git source exists, add repo-based methods (gh skill install <owner>/<repo> --skill <name> or Claude plugin marketplace install). Done when: at least two install methods are generated per skill.
5. Hand the publisher a verification checklist to run after deploy. The checklist contains: digest re-hash against served bytes (curl -sL <url> | sha256sum), tar layout listing (curl -sL <url> | tar -tzf -), real install into a target agent (run one install command and confirm the skill loads), and an activation probe (trigger the skill and confirm it fires). Report each check's result when the publisher runs it, without claiming pre-deploy completion. Done when: the checklist is delivered and any results the publisher provides are recorded.