Agent skill distribution and documentation indexing

[SarthakWade]

Goal

After the user-facing feature set and command contracts stabilize, turn the existing repository-local Headless skill into a versioned, installable, and discoverable integration for Claude Code, Cursor, Codex, OpenCode, and public skill/documentation registries.

This extends #33. It must reuse .agents/skills/headless-computer-use/ as the canonical source rather than creating independent copies that drift.

Scope

• Audit the canonical skill against the final CLI, MCP schema, capabilities, authentication flows, private sessions, artifacts, diagnostics, and cleanup behavior.
• Publish or submit the skill to skills.sh and other compatible Agent Skills registries whose security and maintenance model we accept.
• Provide tested installation and discovery paths for Claude Code, Cursor, Codex, and OpenCode, covering project-local and user-level installation where each client supports it.
• Add registry metadata, version compatibility, license, repository, release, and update information without machine-specific paths.
• Make Headless documentation suitable for Context7 indexing and complete the library submission or onboarding process.
• Verify that Context7 can retrieve current command, setup, security, and troubleshooting documentation. Context7 is a documentation index, not an executable skill package.
• Generate command and capability material from repository sources where practical. Do not manually maintain another command reference.
• Define how skill and Context7 metadata are updated when a Headless release changes the agent-facing contract.
• Add validation for skill frontmatter, internal links, scripts, metadata, generated content, and forbidden local paths or secrets.
• Record smoke-test evidence that fresh Claude Code, Cursor, Codex, and OpenCode sessions can discover the integration and complete a small semantic browser task without invented commands.

Contracts to preserve

• No arbitrary JavaScript command, TCP listener, debug port, or unsafe navigation shortcut.
• Page-derived content remains untrusted and must never be treated as instructions.
• Agents must inspect before acting, avoid guessed references or coordinates, re-inspect after navigation, and clean up only resources they started.
• Sensitive values, credential contents, storage values, and local filesystem paths must not enter skill output, registry metadata, examples, or test evidence.
• Vendor-specific adapters must remain generated from or linked to the canonical skill.

Dependencies and timing

Start implementation only after the scheduled user-facing feature and command issues are complete enough for the agent contract to be stable. This does not depend on Apple Developer credentials or notarization. Recheck registry formats and client installation mechanisms when implementation begins because those external contracts may change.

Acceptance criteria

• One canonical skill source produces or validates every supported adapter.
• Claude Code, Cursor, Codex, and OpenCode installation instructions are tested from a clean environment.
• The chosen skill registries list a versioned Headless skill with correct repository and security metadata.
• Context7 indexes the intended documentation and retrieval checks return current commands and security guidance.
• CI catches stale generated command content, broken links, invalid metadata, local paths, and secret-like values.
• Release documentation states when and how skill and Context7 entries are refreshed.
• Existing protocol, security, and cleanup tests remain green.