Create Issue

Create GitHub Issue

Create a detailed, unambiguous GitHub issue, optionally adding it to a GitHub Project (v2) and setting status. All project metadata (ids, fields, options, milestones, labels, issue types) is read from the local cache .local/gh-projects.json, provisioned out-of-band by ~/Scripts/provision-repo-config.py. This skill never enumerates or refreshes project metadata.

Inputs

• target (argument): the project name (a key in .local/repos.json) whose repo receives the

issue. If omitted, ask the user (or default to the sole entry).

• issue-type (optional argument): bug | feature | task | chore | …. If omitted, infer

from the conversation and confirm with the user before creating.

• Conversation context: description, evidence, reproduction steps, expected vs. actual behavior,

acceptance criteria, etc.

Configuration & cache

• .local/repos.json (walk up from pwd) is a JSON object keyed by name:

{ "": { "path": "...", "github": { "owner", "repo", "project", "wiki_path" } } }. github.project is a Project title; "" means "no associated project — file a plain issue"; absent/null means "not yet resolved".

• .local/gh-projects.json (keyed by ``) holds the resolved

ids/fields/milestones/labels/issue types.

Both files are provisioned by ~/Scripts/provision-repo-config.py, run once per repo. This skill reads them and never writes or refreshes them.

Process

1. Resolve the project & cache (cheap checks first)

1. Read the ` entry from .local/repos.json (jq '.[""]'`). If the file or the

entry is missing, tell the user to run ~/Scripts/provision-repo-config.py in this repo, then stop.

1. Branch on github.project:

• "" → create a plain repo issue (skip project add/status).
• non-empty title → load .local/gh-projects.json and look up the `` key. If the

cache file or that key is missing, tell the user to run ~/Scripts/provision-repo-config.py in this repo, then stop.

• absent / null (unresolved) → the project has not been provisioned. Tell the user to run

~/Scripts/provision-repo-config.py in this repo, then stop.

After this step you either have a cache entry for `, or github.project == ""` (plain issue).

2. Determine issue type, labels, and title prefix

• If the user passed/named a type, use it; otherwise infer it from the conversation and **confirm

with the user** before creating.

• Map type → label(s) + Conventional-Commit prefix:

| Type | Prefix | Default labels | |------|--------|----------------| | bug | fix: | bug (+api if an API endpoint is involved) | | feature | feat: | enhancement | | task | chore: | (none, or chore if it exists) | | chore | chore: | (none, or chore if it exists) |

• Only apply labels that exist in the cache's labels list. If a desired label is missing, omit it

and note the omission (the cache refreshes only by re-running the provisioning script).

• If the cache issue_types is non-empty and contains a matching type, pass --type "" to

gh issue create.

3. Determine milestone from branch

BRANCH=$(git branch --show-current)

Look for a cache milestone whose title exactly equals $BRANCH. If found, use it. If $BRANCH is not main and no milestone matches, create without a milestone (the cache may be stale; re-run the provisioning script to refresh).

4. Build the body (by type)

Use a template matched to the issue type. Omit sections that don't apply.

Bug:

## Summary

## Steps to Reproduce
1. 

## Expected Behavior

## Actual Behavior

## Evidence

## Possible Cause

## Impact

## Environment

Feature / Task:

## Summary

## Acceptance Criteria
- [ ] 

## Notes

5. Create the issue

gh issue create --repo "$OWNER/$REPO" \
  --title " " \
  --label "" \
  ${ISSUE_TYPE:+--type "$ISSUE_TYPE"} \
  ${MILESTONE:+--milestone "$MILESTONE"} \
  --body "$(cat 
EOF
)"

Capture the issue URL and number.

6. Add to the project & set status (only if a cache entry exists)

Read ids from the cache entry for ``:

• project.number, project.owner, project.id
• fields.Status.id and the option id for the chosen status from fields.Status.options

gh project item-add "" --owner "" --url "$ISSUE_URL"

ITEM_ID=$(gh project item-list "" --owner "" \
  --format json --limit 200 \
  | jq -r --argjson n "$ISSUE_NUMBER" '.items[] | select(.content.number==$n) | .id')

gh project item-edit --project-id "" --id "$ITEM_ID" \
  --field-id "" --single-select-option-id ""

Default status (policy, not cached): choose the option named like "This milestone" if present; otherwise the first option in fields.Status.options. The caller may override by naming a status; match it case-insensitively against option names.

If a needed value (status option, etc.) is absent from the cache, proceed without it and note the omission — never loop. Re-run the provisioning script to refresh the cache.

7. Report

Created: 
  Type:       ()
  Labels:    
  Milestone: 
  Project:    ()

Error Handling

| Situation | Behavior | |---|---| | gh not authenticated | Tell the user to run gh auth login. | | Target not in .local/repos.json | Error with the list of known names. | | github.project == "" | Create a plain issue; skip project add/status. | | Cache file/entry missing | Tell the user to run ~/Scripts/provision-repo-config.py, then stop. | | Individual value missing (label/status option) | Proceed without it and note the omission. | | Milestone not found (after one refresh) | Create without a milestone. | | gh project item-add / status edit fails | Report; the issue still exists. |

Implementation Notes

1. Cache is the source of ids. This skill never enumerates or refreshes project metadata;

provisioning is done out-of-band by ~/Scripts/provision-repo-config.py. When a required cache entry is missing, the skill stops and asks the user to run it; individual missing values are skipped with a note.

1. Evidence quality matters for bugs: include actual payloads and field values.
2. Conventional-Commit prefixes by type as in the table above.
3. Branch → milestone: exact title match; no fuzzy matching.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ericfitz
• Source: ericfitz/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.