Skill Sharing

Last verified against implementation: 2026-07-15

Skill Sharing packages one of Vita's agent skills as a public, browsable, agent-ingestible snapshot at https://vita-reports.ham.xyz/sk/<token>.

The system is designed for a specific handoff problem: copying a SKILL.md directory is not enough when it contains Vita-specific paths, tools, people, services, or operating assumptions. Every share therefore requires a human- or agent-authored PORTING.md that tells the receiving agent what is portable, what must be installed, and what must be adapted.

The public share offers:

a file tree and source viewer;
copy and per-file download controls;
a complete zip archive;
manifest.json for machine-readable discovery;
llms.txt as an agent entrypoint; and
raw file endpoints suitable for direct ingestion.

End-to-end flow

.claude/skills/<name>/
          │ snapshot (excluding caches, VCS dirs, virtualenvs)
          ▼
data/skill-shares/<name>/
├── PORTING.md          required adaptation guide
├── skill/              frozen skill files
├── manifest.json       metadata + serving allowlist
├── llms.txt            receiving-agent entrypoint
└── <name>.zip          complete portable bundle
          │
          ▼
POST /api/v1/skillshare/share
          │ stable token per skill name
          ▼
https://vita-reports.ham.xyz/sk/<token>
          │
          ├── browser
          ├── /manifest.json
          ├── /llms.txt
          ├── /raw/<listed-path>
          └── /zip

The public routes serve the frozen snapshot, never the live skill directory. Editing a local skill after publication does not silently change what a recipient sees; republishing refreshes the snapshot while retaining the same token for that skill name.

The judgment step: `PORTING.md`

data/skill-shares/<name>/PORTING.md is mandatory. Publication stops if it is missing because it carries the part that cannot be generated mechanically.

A useful guide is written to the receiving agent and covers:

what the skill does;
a per-file portability map;
required binaries, fonts, APIs, devices, and services;
every Vita-specific path, wrapper, harness feature, identity reference, or personal assumption that must be replaced;
dependencies on other skills, with the essential behavior inlined or marked optional; and
an installation sequence ending in a dry run before real side effects.

This is also the privacy review. The publishing agent reads the skill fresh, checks for secrets and personal data, and edits the frozen snapshot when a redaction is required.

Publishing

The workflow is defined by .claude/skills/skill-share/SKILL.md and implemented by scripts/skillshare/publish.py:

PYTHONPATH=scripts uv run python -m skillshare.publish <name> \
  --title "Human-readable title"

For a skill outside .claude/skills/, pass --skill-dir <path>.

The command performs five ordered phases:

Phase	Behavior
Snapshot	Copies files into `data/skill-shares/<name>/skill/`; excludes caches, `.git`, `node_modules`, virtual environments, and compiled Python files
Guide gate	Refuses to continue without `PORTING.md`
Package	Builds the manifest, `llms.txt`, and zip
Mint	Creates or reuses a token in the shared report registry
Verify	Fetches the browser, manifest, a raw file, and zip through the public domain

Success is not reported until all four public-domain checks pass. --no-verify exists for controlled diagnostics, but it deliberately produces an unverified result and should not be used for a real handoff.

Token and storage model

Skill Sharing reuses the report-sharing registry at data/reports/.shares.json. A skill token has kind: "skill", which lets the public router distinguish it from reports and canvas shares. Minting is idempotent by skill name: republishing updates files behind the existing link instead of creating a trail of obsolete URLs.

The token is unguessable, but possession of the URL grants public read access. It is not authentication. Revocation removes the token entry from the shared registry; the frozen files may remain on disk but become unreachable through the router.

Public serving boundary

api/src/routers/skillshare_public.py provides two different surfaces:

internal minting at POST /api/v1/skillshare/share; and
public, token-scoped reads below /sk/<token>.

The domain guard allowlists /sk/ on vita-reports.ham.xyz while keeping the minting route internal. Raw paths are not arbitrary filesystem paths: a file must appear in manifest.json, and its resolved path must remain inside the snapshot. The manifest therefore doubles as the serving allowlist.

Text source is served with explicit UTF-8 types. HTML and JavaScript inside a skill are served as text, not executed as share-page content. The browser itself is self-contained and uses no third-party CDN.

Receiving-agent protocol

The handoff sentence is intentionally small:

Start at https://vita-reports.ham.xyz/sk/<token>/llms.txt.

That file directs the agent to read PORTING.md, inspect the manifest, fetch the remaining raw files or zip, install them into its own skill directory, and apply the documented adaptations. A receiving agent should not blindly copy the bundle into production because Vita paths and side-effect tools may not exist—or may mean something different—in its environment.

Known limitations and improvement opportunities

Tokens are bearer links with no expiration or recipient identity.
Revocation is currently a registry operation rather than a dedicated command.
PORTING.md quality is judgment-dependent; the packager validates presence, not completeness.
Republish keeps the stable URL but does not expose snapshot versions or a change history to recipients.
The public browser is implemented as an inline HTML response, making visual changes harder to test than a separate template.
Publication verification checks reachability and basic content, not whether a second agent can successfully install and dry-run the skill.

Useful improvements would be an explicit revoke command, optional expirations, a generated snapshot diff on republish, a porting-guide lint, and a disposable recipient-agent installation test.

File map

Purpose	Path
Sharing workflow	`.claude/skills/skill-share/SKILL.md`
Snapshot and publish pipeline	`scripts/skillshare/publish.py`
Public and internal routes	`api/src/routers/skillshare_public.py`
Frozen snapshots	`data/skill-shares/<name>/`
Shared token registry	`data/reports/.shares.json`
Domain allowlist	`api/src/middleware/domain_guard.py`

Changelog

2026-07-15: Initial documentation for the skill-share workflow, scripts/skillshare publisher, and skillshare_public serving surface.