create-discussion

Files (1)

• SKILL.md

SKILL.md (first lines)

# Create GitHub Discussion

Creates a structured GitHub Discussion in the specified repository with background, prioritized acceptance criteria (Must/Should), and (for private repositories) a justified time budget.
Use it for repositories that route requests (typically feature requests) to GitHub Discussions instead of issues, so the request arrives in the channel the maintainers asked for.
This skill is standalone: it is the Discussion counterpart to `/create-issue` and does not participate in the issue-driven SDLC pipeline.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, operate on `$REPO`.
- `gh` CLI authenticated with write access to the target repository, and Discussions enabled for it
- Repository name in `owner/repo` format (`$1`), or omitted to use the repository in the current working directory

### Skill attribution (GitHub)

Before creating the discussion with `createDiscussion`, read [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md) and append the **Created with** footer for `SKILL_DIR` = `create-discussion` to the discussion body.
The SDLC phase footer does not apply: a discussion is not issue-driven and has no issue number.

### Communication guidelines (outbound text)

Before composing any text posted or drafted on the user's behalf, apply [`communication-guidelines/SKILL.md`](../communication-guidelines/SKILL.md).

## Formatting

- Do not use curly or typographic quotation marks in any text you write for the discussion (title, body, sections, lists, or examples).
  Use straight ASCII double quotes (`"`) and straight apostrophes (`'`) only.
- Write one sentence per line throughout the discussion body.
  Lists and checklist items follow their own format, but any prose paragraph should have each sentence on its own line.

## Acceptance Criteria

- Split into **Must** (the exit gate, the minimum bar for "done") and **Should** (deferrable without blocking the request).
- Aim for the smallest set that proves the request is resolved.
  If **Must** grows beyond roughly 5 items, the request is probably too broad and should be split rather than padded with more criteria.
- Each criterion must be testable (a concrete test can be written for it) and specific about *what*, not *how*.
- Put the happy path in **Must**.
  Move edge cases, error handling, and polish to **Should** unless they are part of the core definition of done.
- Omit the **Should** subsection entirely when there are no deferrable items.
  Do not invent nice-to-haves just to fill it.

## Time Budget

- Give a **total** plus a short **breakdown** so the estimate can be defended and challenged rather than asserted.
- Weight the estimate toward **planning and evaluation**, not implementation.
  With AI-assisted development, writing the code is nearly free and instant; the real cost is understanding the problem, designing the solution, evaluating alternatives, and validating the result.
  Treat implementation sub-estimates as negligible unless the work is genuinely large (e.g. multi-day migrations, hardware-bound work, or mass repetitive changes).
- The breakdown should list the activities that actually limit delivery: research, design, feasibility evaluation, review, and validation/testing.
- Each breakdown line pairs a work area with a sub-estimate and a one-line cost driver (e.g. "unfamiliar codepath", "needs a design decision", "requires cross-team input").
- List the **assumptions** the estimate depends on (what is already in place, what is out of scope).
  When an assumption breaks, the estimate should be revisited.
- Keep it rough: half-day precision is fine.
  Do not over-engineer the breakdown for small requests (a single line is acceptable when the work is genuinely one lump).

## Summary

- If the description (background plus any context you would write) exceeds 200 words, add a **Summary** section before the **Background** section.
- The summary must be less than 200 words, at most 5 sentences, with one sentence per line, and concisely summarize the ask: what is needed and why, in plain terms.
- If the description is 200 words or fewer, omit the Summary section entirely.

## Discussion Body Scope

- Keep the discussion body focused on summary (when applicable), background, acceptance criteria, and time budget.
- If you have detailed code analysis (e.g. files examined, codepaths traced, root-cause reasoning, relevant snippets), do not add it to the body.
  Instead, post it as a follow-up comment after the discussion is created.
- The body should give readers enough context to discuss the request; the follow-up comment provides the deeper analysis for those who want the reasoning.
- Discussions do not support labels or issue types.
  Do not attempt to apply either.

## Steps

1. **Search for duplicates** first, before any codebase investigation.
   The report alone supplies the keywords (error messages, command, skill, or feature names, component names).
   Search Discussions and issues, because a duplicate may already exist in either channel:
   ```
   gh api graphql -f query='
   query($q:String!){ search(query:$q, type:DISCUSSION, first:10){ nodes{ ... on Discussion{ number title url } } } }
   ' -f q='repo:{owner}/{repo} <keywords>'

   ghx issue list --repo $1 --search "<keywords>" --state all --limit 10
   ```
   If a duplicate is found, stop and inform the user with the existing URL.
   Do not create a new discussion unless the user confirms it is not a duplicate.
2. If the request is a feature request, determine the current version on the default branch (main/master) so the discussion records what commit the request was filed against.
   Use `gh api repos/{owner}/{repo} --jq '.default_branch'` to find the default branch, then get the short SHA via `gh api repos/{owner}/{repo}/commits/<default_branch> --jq '.sha[0:7]'`.
3. Determine if the repository is public or private using `gh repo view [--repo $1] --json isPrivate --jq '.isPrivate'`.
   A public repository is treated as open source; omit the **Time budget** section.
   A private repository includes it.
4. **Resolve the repository node ID and the target category**.
   First confirm Discussions is enabled:
   ```
   gh api repos/{owner}/{repo} --jq '{id: .node_id, has_discussions: .has_discussions}'
   ```
   If `has_discussions` is false, stop and tell the user the repository does not accept discussions.
   Then list the categories:
   ```
   gh api graphql -f query='
   query($owner:String!,$name:String!){
     repository(owner:$owner,name:$name){ discussionCategories(first:50){ nodes{ id name slug } } }
   }' -f owner=<owner> -f name=<repo>
   ```
   Pick the target category in this order:
   1. The category the user named.
   2. The category in the repository's feature-request contact link, read from the issue-template config (its URL is `/discussions/categories/<slug>` or `/discussions/new?category=<slug>`):
      ```
      gh api "repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE/config.yml" --jq '.content' 2>/dev/null | base64 -d
      ```
   3. The first category whose `slug` or `name` matches ideas/feature/suggestions (case-insensitive).
   4. The first category.
      If there are no categories, stop and tell the user.
5. **Compose the body and create the discussion.** Include a **Version** section with the default-branch version determined in step 2 for feature requests (omit for requests that are neither).
   Omit `--repo`-style flags: the mutation takes the repository node ID directly.
   Append the attribution footer resolved per [`github-post-attribution/SKILL.md`](../github-post-attribution/SKILL.md):
   ```
   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{ id number url }
     }
   }' -f repoId="<repo_node_id>" -f categoryId="<category_node_id>" -f title="<title>" -f body="$(cat <<'EOF'

From tomzx/agents, MIT.

More from tomzx/agents