the-rabak/deploy-docs

Goal

Validate the documentation site and confirm that the repository is ready for GitHub Pages deployment.

Use this skill when

• Documentation changes need deployment-readiness verification.
• The team needs GitHub Pages setup or deployment instructions.
• The docs site should be checked before merge or release.

Do not use this skill when

• The docs site is not the target of the current work.
• Required documentation assets are knowingly incomplete and not ready to validate.

Non-negotiable rules

• Validate documentation before discussing deployment.
• Check component counts, JSON validity, and required HTML page presence.
• Warn about uncommitted documentation changes before declaring readiness.
• Preserve and present the GitHub Pages workflow requirements.
• Make deployment-readiness status explicit.

Procedure

Execute the full source-of-truth workflow below. Preserve every conditional branch, phase, checklist, and validation step from the original instructions. When the workflow says to ask, wait, route, or run in parallel, do that exactly.

Deploy Documentation Command

Validate the documentation site and prepare it for GitHub Pages deployment.

Step 1: Validate Documentation

Run these checks:

# Count components
echo "Agents: $(ls plugins/compound-engineering/agents/*.md | wc -l)"
echo "Commands: $(ls plugins/compound-engineering/commands/*.md | wc -l)"
echo "Skills: $(ls -d plugins/compound-engineering/skills/*/ 2>/dev/null | wc -l)"

# Validate JSON
cat .claude-plugin/marketplace.json | jq . > /dev/null && echo " marketplace.json valid"
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq . > /dev/null && echo " plugin.json valid"

# Check all HTML files exist
for page in index agents commands skills mcp-servers changelog getting-started; do
  if [ -f "plugins/compound-engineering/docs/pages/${page}.html" ] || [ -f "plugins/compound-engineering/docs/${page}.html" ]; then
    echo " ${page}.html exists"
  else
    echo " ${page}.html MISSING"
  fi
done

Step 2: Check for Uncommitted Changes

git status --porcelain plugins/compound-engineering/docs/

If there are uncommitted changes, warn the user to commit first.

Step 3: Deployment Instructions

Since GitHub Pages deployment requires a workflow file with special permissions, provide these instructions:

First-time Setup

1. Create .github/workflows/deploy-docs.yml with the GitHub Pages workflow
2. Go to repository Settings > Pages
3. Set Source to "GitHub Actions"

Deploying

After merging to main, the docs will auto-deploy. Or:

1. Go to Actions tab
2. Select "Deploy Documentation to GitHub Pages"
3. Click "Run workflow"

Workflow File Content

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches: [main]
    paths:
      - 'plugins/compound-engineering/docs/**'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: 'plugins/compound-engineering/docs'
      - uses: actions/deploy-pages@v4

Step 4: Report Status

Provide a summary:

## Deployment Readiness

 All HTML pages present
 JSON files valid
 Component counts match

### Next Steps
- [ ] Commit any pending changes
- [ ] Push to main branch
- [ ] Verify GitHub Pages workflow exists
- [ ] Check deployment at your GitHub Pages URL

Required output

Return a deployment-readiness report with:

• Validation results for counts, JSON, and HTML pages.
• Whether docs changes are clean or need a commit.
• Whether the Pages workflow exists or must be added.
• The exact next-step checklist for deployment.