Publish Plan
Convert a plan file into a GitHub Discussion post for public input.
Get the complete skill folder, including its scripts and reference files.
This page is available to readers but is excluded from the public index, because it does not yet meet the evaluation standard.
When to use this skill
Use Publish Plan when an AI agent needs a reusable SKILL.md workflow for this job: Convert a plan file into a GitHub Discussion post for public input.
When not to use it
Skip Publish Plan when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/publish-plan # Save SKILL.md to ~/.claude/skills/publish-plan/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/publish-plan/SKILL.md. For a shared project, commit the folder at .claude/skills/publish-plan/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Publish Plan skill for this task: Use Publish Plan when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
65/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 65/100
- Practical detail
- 68/100
- Source evidence
- 56/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# publish-plan
Convert a plan file (release plan, feature spec, or `.cursor/plans/` file) into a GitHub Discussion post written for external readers. Strips internal references and PII, rewrites for a public audience, and optionally posts via the GitHub CLI.
## When to Use
Use when you have a plan in progress and want external input before execution. Pass the path to any plan document as the argument:
``` /publish-plan docs/releases/in_progress/v0.12.0/release_plan.md /publish-plan .cursor/plans/some_plan.md /publish-plan docs/feature_units/in_progress/FU-2026-01-001/FU-2026-01-001_spec.md ```
Optionally pass a specific question to ask readers as a second argument:
``` /publish-plan docs/releases/in_progress/v0.12.0/release_plan.md "Does this sync model work for your use case?" ```
---
## Step 1: Read and Parse the Plan
1. Read the plan file at the provided path. 2. Extract the following from the document: - **Goal / motivation**: Why does this exist? What problem does it solve? - **Approach / key decisions**: What choices were made or are still open? - **Scope boundaries**: What is explicitly excluded or deferred? - **Open questions**: What is uncertain or unresolved?
---
## Step 2: Strip Internal References
Remove or redact anything that should not be public:
- Full names and email addresses of individuals - Internal Slack channels, ticket numbers, or system identifiers that leak org structure - Pricing, cost, or revenue figures - Internal hostnames, credentials, or environment-specific configuration values - Agent execution notes (batch status, orchestrator output, FU dependency trees) - Anything marked `<!-- internal -->` or `[INTERNAL]`
Do not strip: - Feature IDs (FU-YYYY-MM-NNN) — these are useful public references - Architecture decisions and technical rationale - Version numbers and release IDs - Links to public repo files or issues
---
## Step 3: Draft the Discussion Post
Rewrite the extracted content into the following structure. Write in plain prose for an external developer audience. No jargon specific to the foundation framework.
```markdown ## What we're building
[2-3 sentences: the problem being solved and the general approach. No implementation detail.]
## Key decisions
[3-5 bullet points: choices made or still open. Frame as "We chose X because Y" or "We're deciding between X and Y".]
## What's out of scope (for now)
[2-4 bullet points: explicit exclusions that might surprise readers or that they might assume are included.]
## Where we want input
[The specific question. One sentence. Concrete. If the user provided a question, use it here. Otherwise, derive the most useful open question from the plan.]
---
*This is a pre-execution plan. We're sharing it before we build to get early input. Comments and questions welcome.* ```
Apply the content style rules: - Complete sentences throughout - No em dashes, no "leverage", no "seamless", no marketing language - Active voice - 15-20 words per sentence maximum - No filler transitions ("Furthermore", "Moreover", "In addition")
---
## Step 4: Preview and Confirm
Show the drafted post to the user and ask:
``` Here is the Discussion post draft:
--- [post content] ---
Options: 1. Post to GitHub Discussions now (requires gh CLI and Discussions enabled) 2. Copy to clipboard / show as output only 3. Edit — describe what to change ```
Wait for the user's choice before proceeding.
---
## Step 5: Post to GitHub Discussions (if requested)
If the user chooses to post, use the GitHub CLI GraphQL API:
```bash # Get the repository ID and Discussions category ID REPO_OWNER=$(gh repo view --json owner -q '.owner.login') REPO_NAME=$(gh repo view --json name -q '.name')
# List available discussion categories gh api graphql -f query=' query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { discussionCategories(first: 10) { nodes { id name } } } } ' -f owner="$REPO_OWNER" -f name="$REPO_NAME" ```
Use category "RFC / Plans" if it exists. If it does not exist, use the closest match ("Ideas", "General") and note to the user that a dedicated category would be better. Do not create the category automatically.
Post the discussion:
```bash REPO_ID=$(gh api graphql -f query=' query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { id } } ' -f owner="$REPO_OWNER" -f name="$REPO_NAME" -q '.data.repository.id')
CATEGORY_ID="<selected category id>" TITLE="<derived from plan title or release version>" BODY="<the drafted post content>"
gh api graphql -f query=' mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) { createDiscussion(input: { repositoryId: $repoId, categoryId: $categoryId, title: $title, body: $body }) { discussion { url } } } ' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" \ -f title="$TITLE" -f body="$BODY" ```
Report the Discussion URL on success.
---
## Step 6: Follow-up Reminder
After posting (or outputting the draft), remind the user:
``` Remember to reply in the thread once a decision is made. A single note — "We went with X because Y" — closes the loop for anyone who finds the thread later. ```
---
## Error Handling
**gh CLI not installed or not authenticated:** Output the draft post only. Include a note: "Install and authenticate the GitHub CLI (`gh auth login`) to post directly from this skill."
**Discussions not enabled on the repository:** Output the draft post only. Include a note: "Enable Discussions in the repository Settings to use the post step."
**Plan file not found:** Exit with: "Plan file not found: {path}. Pass the path to an existing plan document."
---
## Configuration
No configuration required. The skill reads `foundation-config.yaml` for the repository name and remote when deriving post metadata, but falls back to `gh repo view`.
Intended uses
- Use Publish Plan when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.