deploy-docs_skill

Overview

This skill validates and prepares the Compound Engineering documentation site for GitHub Pages deployment. It runs file existence and JSON validation checks, verifies component counts, and guides you through workflow setup and deployment steps. The goal is a quick readiness report and clear next steps to publish docs from the repository.

How this skill works

It inspects the docs directory and plugin metadata to ensure required HTML pages exist and JSON files are syntactically valid. It counts agent and skill markdown files to surface mismatches, checks for uncommitted changes in the docs tree, and produces a deployment readiness summary. It also supplies a recommended GitHub Actions workflow and step-by-step instructions to enable and run GitHub Pages deployment.

When to use it

• Before merging documentation changes to main to confirm deploy readiness
• When preparing a first-time GitHub Pages setup for the plugin docs
• After adding or removing agents or skills to ensure counts and pages match
• When debugging a failed Pages deployment to verify files and workflow config

Best practices

• Commit and push all docs changes before running deployment checks
• Keep marketplace.json and plugin.json well-formed and validated with jq
• Ensure the docs HTML pages for key routes (index, agents, skills, etc.) exist
• Install a GitHub Actions workflow with pages:write and id-token:write permissions
• Use the provided workflow pattern and limit path triggers to the docs folder

Example use cases

• Run checks in CI to block merges when docs are incomplete or JSON is invalid
• Validate that newly added agent markdown files are reflected in the docs build
• Confirm there are no uncommitted docs edits before triggering a manual workflow run
• Set up the GitHub Pages workflow and verify the deployment URL after first run