Objective
Ship a docs-publisher plugin with portable, project-agnostic skills that let any developer using the agentics marketplace publish their own plan galleries and social media card libraries to GitHub Pages — replicating the same docs/ , build-index.sh , deploy-pages.yml , and serve-docs.sh workflow this project uses, but as installable marketplace skills that adapt to any repo.
Implement
Read and implement all steps in the plan at docs/plans/create-docs-publishing-skills.md — Create Docs Publishing Skills for Plugin Users. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/create-docs-publishing-skills.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Create Docs Publishing Skills for Plugin Users. The plan at docs/plans/create-docs-publishing-skills.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/create-docs-publishing-skills.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/create-docs-publishing-skills.md — Create Docs Publishing Skills for Plugin Users. Brief subagents with the plan file at docs/plans/create-docs-publishing-skills.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/create-docs-publishing-skills.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File
create-docs-publishing-skills.html
Path
docs/plans/create-docs-publishing-skills.html
Spec
docs/plans/create-docs-publishing-skills.md
Definition of done
0 / 8 done
Context
The story behind this plan — what prompted the work and why it matters now.
The agentics project publishes two browsable galleries to GitHub Pages: a Plans gallery (filterable index of all HTML implementation plans) and a Social cards library (dark-mode card images generated from code changes). These are built by docs/plans/build-index.sh , social-media-tools templates, a PostToolUse auto-rebuild hook, a local preview server ( scripts/serve-docs.sh ), and a GitHub Actions deploy workflow ( .github/workflows/deploy-pages.yml ).
Developers who install the agentics plugins ( plan-agent , social-media-tools ) in their own projects get the plan-writing and social-card-generation skills but have no turnkey way to publish those artifacts to GitHub Pages . They would need to manually replicate the docs infrastructure: scaffold the directory, copy templates, create the workflow, and wire up the build scripts. This plan creates a dedicated docs-publisher plugin that packages the entire pipeline as installable skills.
Key decisions (resolved): The plugin is standalone with no peer dependencies on plan-agent or social-media-tools — it detects which content exists and gracefully skips empty galleries. Build scripts are copied into the user's project by docs-init so they are version-controlled, editable, and survive plugin uninstall.
Files that change
Every file this plan touches, and what happens to each one.
agentics/
kit/plugins/docs-publisher/.claude-plugin/plugin.jsonnew plugin manifest- kit/plugins/docs-publisher/commands/
docs-init.mdnew one-shot project scaffolding commanddocs-publish.mdnew build + commit + push orchestration
docs-build/SKILL.mdnew gallery index regeneration skilldocs-serve/SKILL.mdnew local HTTP preview serverkit/plugins/docs-publisher/hooks/auto-rebuild-gallery.pynew PostToolUse hook for auto gallery rebuild- kit/plugins/docs-publisher/templates/
landing-hub.htmlnew docs/ root index with card gridplans-gallery.htmlnew filterable plan gallery with status/type badgessocial-gallery.htmlnew dark-mode social card gallery
- kit/plugins/docs-publisher/scripts/
build-plans-index.shnew portable plans gallery builderbuild-social-index.shnew portable social cards gallery builderserve-docs.shnew portable local HTTP server
kit/plugins/docs-publisher/reference/deploy-pages.ymlnew GitHub Actions workflow template- kit/plugins/docs-publisher/
README.mdnew plugin documentationCHANGELOG.mdnew initial changelog
.claude-plugin/marketplace.jsonmodified register docs-publisher plugin
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
1
todo
Scaffold the docs-publisher plugin skeleton
Why
The plugin needs a manifest and directory structure before any skills can be added. Creating the skeleton first establishes the canonical layout that all subsequent steps write into.
Verify
Run ls kit/plugins/docs-publisher/.claude-plugin/plugin.json and confirm it exists with name: "docs-publisher" . Confirm README.md and CHANGELOG.md exist in the plugin root.
2
todo
Create the docs-init command for one-shot project scaffolding
Why
This is the entry point for any developer adopting the docs publishing workflow. A single /docs-publisher:docs-init invocation should set up the complete directory tree, deploy workflow, and landing hub, and copy build scripts into the user's project so they are version-controlled, editable, and survive plugin uninstall.
Verify
Read kit/plugins/docs-publisher/commands/docs-init.md . Confirm the frontmatter has description and the body includes steps to: (1) create docs/ , docs/.nojekyll , docs/plans/ , docs/media/social/ ; (2) write docs/index.html from the landing-hub template; (3) copy deploy-pages.yml into .github/workflows/ ; (4) copy build-plans-index.sh and build-social-index.sh into the project's scripts/ directory; (5) copy serve-docs.sh into scripts/ . Confirm idempotency: existing files should not be overwritten without user confirmation. Confirm the command detects which content types exist (plans, social cards) and only creates gallery directories for present content, skipping gracefully for the rest.
3
todo
Ship portable gallery templates: landing hub, plans gallery, and social gallery
Why
The templates are the visual layer of the published site. They must be self-contained HTML with no CDN dependencies, use the same {{VARIABLE}} substitution pattern as the existing agentics templates, and adapt to any project name — not hard-code "Agentics".
Verify
Open each template in a browser. Confirm: (1) landing-hub.html has {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} placeholders and renders a 2-card grid linking to plans/index.html and media/social/index.html ; (2) plans-gallery.html has {{GALLERY_ENTRIES}} , {{PLAN_COUNT}} , {{GENERATED_AT}} placeholders and includes status/type filter chips; (3) social-gallery.html has equivalent placeholders and uses the dark-mode GitHub-style theme. None reference external CSS or JS.
4
todo
Create portable build scripts for plans and social gallery indexes
Why
The build scripts are the engine that scans plan files and social card images, extracts metadata, and writes index.html gallery pages. Since they are copied into the user's project by docs-init , they must be self-contained and project-agnostic: resolve the plans directory from .claude/settings.json > docs/plans/ fallback, locate gallery templates from the plugin cache (for substitution) or fall back to an embedded minimal gallery, and work on both macOS and Linux.
Verify
Read scripts/build-plans-index.sh . Confirm it: (1) resolves the plans directory using the same resolve_plans_dir() pattern as the existing build-index.sh ; (2) locates templates from the docs-publisher plugin cache path; (3) outputs index.html to the plans directory. Read scripts/build-social-index.sh and confirm the same pattern for social cards under docs/media/social/ .
5
todo
Create the docs-build skill for gallery index regeneration
Why
A skill (auto-activated) rather than a command because gallery rebuilds should trigger naturally when the user says "rebuild the docs gallery" or "regenerate the plan index." The skill invokes the project-local copies of the build scripts (placed by docs-init ) and reports what changed. Gracefully skips a gallery if its script or content directory is absent.
Verify
Read skills/docs-build/SKILL.md . Confirm frontmatter has name: docs-build , a description that triggers on "rebuild gallery"/"regenerate index" intent, and allowed-tools: Bash, Read, Glob . The body should: (1) locate project-local scripts/build-plans-index.sh and scripts/build-social-index.sh ; (2) run each only if the corresponding script and content directory exist; (3) report the count of entries generated per gallery.
6
todo
Create the docs-serve skill for local HTTP preview
Why
Developers need to preview galleries locally before pushing to GitHub Pages. A skill is better than a command here because "serve my docs" or "preview the docs site" should auto-activate without requiring the plugin name prefix.
Verify
Read skills/docs-serve/SKILL.md . Confirm it: (1) finds a free port via Python socket; (2) starts python3 -m http.server from the docs/ directory; (3) prints URLs for both galleries; (4) triggers a gallery rebuild before serving if any index is stale or missing.
7
todo
Create the docs-publish command for build + commit + push orchestration
Why
Publishing is a destructive action (pushes to remote) that should be explicit, not auto-activated. The command orchestrates: rebuild galleries → git add docs/ → commit → push → report the Pages URL. Includes a --dry-run flag to preview what would be committed without pushing.
Verify
Read commands/docs-publish.md . Confirm it: (1) runs both build scripts; (2) stages only docs/ files; (3) creates a conventional commit ( docs: rebuild galleries ); (4) pushes to the current branch; (5) reports the GitHub Pages URL derived from the remote. Confirm --dry-run flag is documented and respected.
8
todo
Create the auto-rebuild PostToolUse hook
Why
The hook automatically regenerates the plans gallery when a plan HTML file is written, matching the behavior of plan-agent 's existing rebuild-plans-index.py . It invokes the project-local scripts/build-plans-index.sh (placed by docs-init ), so it works even if the plugin is later uninstalled.
Verify
Read hooks/auto-rebuild-gallery.py . Confirm it: (1) fires on PostToolUse for Write/Edit; (2) checks if the written file is under docs/plans/ and ends in .html ; (3) debounces rapid writes (2-second window); (4) invokes the project-local scripts/build-plans-index.sh (not a plugin-cache path); (5) silently skips if the script is not found (project hasn't run docs-init yet); (6) always exits 0 (never blocks the write).
9
todo
Register docs-publisher in the marketplace and create the reference deploy workflow
Why
The plugin must be discoverable via the marketplace for users to install it. The reference deploy-pages.yml is a GitHub Actions template that docs-init copies into the user's repo — it triggers on docs/** changes and handles the standard GitHub Pages artifact upload.
Verify
Run cat .claude-plugin/marketplace.json | python3 -c "import sys,json; d=json.load(sys.stdin); print([p['name'] for p in d['plugins']])" and confirm docs-publisher appears. Read reference/deploy-pages.yml and confirm it has the same structure as .github/workflows/deploy-pages.yml but with a {{DOCS_PATH}} placeholder for the docs directory.
Tests
The tests that prove the change does what it promises.
Tier 1 — Code-touching plan
Objective docs-publisher scaffolds a working GitHub Pages site from scratch File: tests/docs-publisher/docs-publisher-e2e.test.sh Type: smoke test Asserts: Running docs-init in a fresh git repo creates the full directory tree ( docs/ , docs/.nojekyll , docs/index.html , docs/plans/ , docs/media/social/ , .github/workflows/deploy-pages.yml ), then running docs-build generates valid index.html gallery files that contain no unfilled {{PLACEHOLDER}} tokens. Run: bash tests/docs-publisher/docs-publisher-e2e.test.sh
Unit Build script metadata extraction File: tests/docs-publisher/build-script-unit.test.sh Targets: build-plans-index.sh Python metadata parser ( get_meta() , get_title() ) Key cases: Extracts <meta name="plan-status"> from valid plan HTML; returns fallback values for missing meta tags; handles HTML entities in titles without double-encoding; skips archive/ subdirectory
Integration Template resolution across installation methods File: tests/docs-publisher/template-resolution.test.sh Targets: find_templates_dir() in build-plans-index.sh and build-social-index.sh Key cases: Finds templates when plugin is installed via marketplace cache ( ~/.claude/plugins/cache/ ); finds templates when plugin is loaded locally ( --plugin-dir ); selects highest-versioned template when multiple versions exist; falls back to embedded minimal gallery when no template found
Integration Auto-rebuild hook debounce and trigger File: tests/docs-publisher/hook-rebuild.test.sh Targets: hooks/auto-rebuild-gallery.py Key cases: Triggers rebuild when a .html file is written under docs/plans/ ; does not trigger for non-HTML files; debounces rapid writes within 2-second window; always exits 0 even if the build script fails
Definition of done
The plan counts as done when every statement below is true — check each one off as you verify it.
Final check
One last pass to confirm the whole change works end to end.
End-to-end verification in a clean environment:
Create a fresh git repo: mkdir /tmp/test-docs && cd /tmp/test-docs && git init
Load the plugin: claude --plugin-dir ~/devbox/agentics/kit/plugins/docs-publisher
Run /docs-publisher:docs-init and confirm the full directory tree is created with no errors
Copy a sample plan HTML file into docs/plans/
Say "rebuild the docs gallery" and confirm the docs-build skill activates and generates docs/plans/index.html
Say "serve my docs" and confirm the docs-serve skill starts a server; open both gallery URLs in a browser
Run /docs-publisher:docs-publish --dry-run and confirm it lists the files that would be committed without actually pushing
Confirm the auto-rebuild hook fires when a new plan HTML is written to docs/plans/
Wrapping up
Three gates that must all pass before this plan is marked completed.
Required
Completion Report
No items to report — all requirements met.