docs(readme): rewrite Quick Start, expand Skills tables, fix workflow#10
Merged
docs(readme): rewrite Quick Start, expand Skills tables, fix workflow#10
Conversation
- Replace fictional install commands with real /plugin (Claude Code) and copilot plugin (Copilot CLI) marketplace + install syntax. Both ecosystems can install pharaoh via the existing .claude-plugin/marketplace.json (Copilot also looks there). - Mirror marketplace.json at .github/plugin/marketplace.json so Copilot users find it at the GitHub-native location. Add CI check enforcing the two files stay byte-identical. - Rewrite the Workflow diagram to reflect plan-driven orchestration (pharaoh:write-plan + pharaoh:execute-plan) introduced in PR #9; the previous diagram still showed the deleted composition-skill model. - Expand the Skills section from 24 to 71 entries, regrouped into 8 categories: core workflow, plan-driven orchestration, atomic authoring/review, diagrams, feature reverse-engineering, analysis & audit, tailoring, setup utilities. - Fix three description drifts (pharaoh:spec, pharaoh:flow, pharaoh:process-audit) where README disagreed with each skill's SKILL.md. - Fix dead sphinx-codelinks URL (sphinx-codelinks.useblocks.com → codelinks.useblocks.com). - Drop orphan [pharaoh.decisions] section from pharaoh.toml.example; no skill reads it. Refs #8.
There was a problem hiding this comment.
Pull request overview
Updates Pharaoh’s documentation and CI to reflect the current plugin installation flow and the plan-driven orchestration model, while expanding the public skill catalog and adding a mirrored marketplace manifest for GitHub Copilot.
Changes:
- Rewrites README Quick Start and Workflow sections for marketplace-based installs and
write-plan/execute-planorchestration. - Expands the README Skills / Agents tables to cover the full current skill set and updates a dead codelinks URL.
- Adds
.github/plugin/marketplace.jsonand a CI check to enforce it stays byte-identical with.claude-plugin/marketplace.json; removes the unused[pharaoh.decisions]section frompharaoh.toml.example.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
README.md |
Updates install instructions, workflow diagram, skills tables, and fixes a codelinks URL. |
pharaoh.toml.example |
Removes the orphan [pharaoh.decisions] section. |
.github/workflows/ci.yaml |
Adds a CI step to ensure marketplace manifests remain identical. |
.github/plugin/marketplace.json |
Adds a GitHub-native copy of the plugin marketplace manifest. |
Pharaoh's skill names already include the `pharaoh-` prefix (e.g. SKILL.md frontmatter `name: pharaoh-setup`), so the Claude Code slash namespace lands on `/pharaoh:pharaoh-setup`, not `/pharaoh:setup`. Verified against the installed plugin: chrome-devtools-mcp's skills are named cleanly (`troubleshooting` -> `/chrome-devtools-mcp:troubleshooting`), while pharaoh and papyrus self-prefix (`pharaoh-setup` -> `/pharaoh:pharaoh-setup`). The Copilot side already strips the prefix in agent file names (`.github/agents/pharaoh.setup.agent.md` -> `@pharaoh.setup`), so the two ecosystems address skills asymmetrically. README now documents the asymmetry up front and uses the Claude Code form throughout the tables and Quick Start.
Adopt the layout used by github/copilot-plugins (the official Copilot default marketplace): .github/plugin/marketplace.json is the source of truth, .claude-plugin/marketplace.json is a symlink (git mode 120000) to ../.github/plugin/marketplace.json. This keeps a single source of truth -- both Claude Code (which checks .claude-plugin/) and Copilot CLI (which prefers .github/plugin/) find the same file with no drift possible. Drops the CI diff check that was guarding against the previous duplicate-file approach.
- s/Analyse/Analyze/ in pharaoh:change row to match Quick Start's
variant ("Analyze the impact of a change") used elsewhere in the doc.
- Workflow section now correctly describes pharaoh:pharaoh-write-plan
as a pure transformation that returns plan.yaml content as text. The
previous wording said it "emits .pharaoh/plans/<intent>.yaml", which
contradicts the skill's SKILL.md ("Pure transformation: intent +
project state -> plan text. Does not write artefacts. Does not mutate
.pharaoh/."). The caller saves the YAML and hands the path to
pharaoh:pharaoh-execute-plan.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #8.
/plugin marketplace add useblocks/pharaoh+/plugin install pharaoh@pharaoh-devcopilot plugin marketplace add useblocks/pharaoh+copilot plugin install pharaoh@pharaoh-devgithub/copilot-plugins(the official Copilot default marketplace):.github/plugin/marketplace.jsonis the source of truth and.claude-plugin/marketplace.jsonis a symlink (git mode120000) pointing at it. Single source, no drift possible.name: pharaoh-setup), so the Claude Code invocation is/pharaoh:pharaoh-setup(doubled), while the Copilot agent files strip the redundant prefix and expose@pharaoh.setup.pharaoh:pharaoh-write-plan+pharaoh:pharaoh-execute-plan); the previous diagram still showed the deleted composition-skill model.pharaoh-spec,pharaoh-flow,pharaoh-process-audit).sphinx-codelinks.useblocks.comURL →codelinks.useblocks.com.[pharaoh.decisions]section frompharaoh.toml.example; no skill reads it.Empirical verification
marketplace.json:copilot plugin marketplace listshowspharaoh-dev (GitHub: useblocks/pharaoh)copilot plugin listshowspharaoh@pharaoh-dev (v0.1.0)~/.claude/plugins/installed_plugins.jsonincludespharaoh@pharaoh-devcopilot plugin ...,gh copilot plugin ...(passthrough),/plugin install ...,/plugin marketplace add ....ls skills/ | grep -v shared | wc -l.Test plan
copilot plugin marketplace add useblocks/pharaoh+copilot plugin install pharaoh@pharaoh-devround-trip on a clean machine./plugin marketplace add useblocks/pharaoh+/plugin install pharaoh@pharaoh-dev+/reload-pluginsin Claude Code.git cloneon Windows (or documentcore.symlinksrequirement if it does not).