agentleFS
lautioliverlautioliver/barrilete-kit/.claude/skills/create-issue/SKILL.md

create-issue

Skill6 starsChanged 7 days agoMITView on GitHub

Opens loose GitHub issues from a chat request, following the project convention (title, labels, body), turns audits into issues and marks blockers between existing issues ("blocked by"). Use with "open an issue", "create a ticket", "log this as a bug", "turn this audit into issues", "this depends on #12", "block #30 until #25 closes". To plan a feature with several issues, use plan-feature; for "what can I do now?", use project-status.

65 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use native-nostalgia-stack, software-engineering-excellence and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • frostneySkill

    native-nostalgia-stack

    Applies the user's FreePascal toolchain and its build, formatting, hook, and test contracts while leaving project-specific mechanics local. Use when scaffolding or working in a FreePascal project that follows this toolchain.

    Also in 3 projects that use this

  • frostneySkill

    software-engineering-excellence

    Applies the user's engineering standards during substantial technical work: preserve scope, use current evidence, delegate independent parts, and complete authorized outcomes. Use during substantial implementation, debugging, refactoring, or multi-part delivery work.

    Also in 3 projects that use this

  • withpiperSkill

    roadmap-review

    Audit roadmap health — issues, dependency order, spec coverage, doc freshness. Use when speccing a new initiative. Use when /phase-plan output looks suspicious. Use before /roadmap-create reruns.

    Also in 3 projects that use this

  • Microsoft AzureSkill

    create-release

    Use when creating a new ASO release, including pre-checks, release notes generation, draft GitHub release creation, documentation updates, and ROADMAP changes.

    Also in 4 projects that use this

  • MicrosoftSkill

    update-pr

    Update the pull request for the current session. Use when the user wants to push new changes to an existing PR.

    Also in 3 projects that use this

  • SentrySkill

    create-pr

    Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines.

    Also in 25 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 13 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 55 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .github/labels.yml every time: it is the only valid list of labels.

    line 17
  2. Distinctive:

    If there is a similar open one, show it and ask whether to comment there instead of opening another.

    line 28
  3. Distinctive:

    If it comes from an audit or ADR, the link to the document and the ID of the finding or rule.

    line 54
  4. Distinctive:

    Never secrets, tokens or real personal data.

    line 55
  5. Distinctive:

    Create: Write the body to a temporary file so the escaping does not break:

    line 60
  6. Distinctive:

    Blockers: If there are dependencies, record them after creating all the issues of the batch (the new ones have no number before).

    line 73
  7. Distinctive:

    When the request is "turn audit X into issues":

    line 79
  8. Distinctive:

    If the document has no IDs, propose adding them before opening the issues.

    line 82
  9. Distinctive:

    After creating them, offer to note the issue number next to each finding in the document.

    line 83
  10. Distinctive:

    Do not confuse with sub-issues: a sub-issue is a part of the parent's work.

    line 89
  11. Distinctive:

    When creating a batch where the order is obvious (schema before migration, API before the screen that consumes it).

    line 94
  12. Distinctive:

    Do not mark it just because two issues touch the same area.

    line 95
  13. Very specific:

    When blocking an open issue by another open one, add the status:blocked label and a line at the end of the body: Blocked by #A: <why>.

    line 115
  14. Distinctive:

    If the blocking one is already closed, the blocker makes no sense: say so instead of creating it.

    line 116
  15. Very specific:

    No cycles: Before creating B blocked by A, check that A is not blocked (directly or indirectly) by B, walking A's blocked_by.

    line 117
  16. Distinctive:

    If the API answers 404 or 422 (repo without dependencies enabled, issue from another repo without permission), say so with the error and …

    line 119

“Common” is measured: kept by at least 6 in 10 of the 55 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create an issue

It turns a natural-language request into one or several issues that follow docs/github-naming-convention.md §4–5, and records which issue blocks which with GitHub's native dependencies.

It is not for:

  • Planning a feature across several issues (epic, sub-issues, order) → skill plan-feature.
  • "What can I do now?" → skill project-status (available.sh).

Requirements

  • gh authenticated (gh auth status). If it is not, ask the user to run gh auth login; do not go on.
  • Read .github/labels.yml every time: it is the only valid list of labels. Never create new labels or use one that is not there.

Steps

  1. Understand the request. Work out how many issues there are: a request can bring several problems, and an audit brings one per finding. If something essential is missing (what fails, or what needs to be achieved), ask once; do not invent data. Also detect dependencies: phrases like "depends on", "after", "first we need", "blocked by", "once #12 is done". Note which one blocks which (see Blockers).
  2. Look for duplicates.
    gh issue list --state all --search "<keywords>" --limit 10
    If there is a similar open one, show it and ask whether to comment there instead of opening another.
  3. Pick the type (exactly one type: label):
    RequestLabelBody template
    Something does not work as definedtype:bug.github/ISSUE_TEMPLATE/1-bug.yml
    New functionality or visible changetype:feature2-feature.yml
    Technical work with no visible changetype:task3-task.yml
    Finding from an audittype:audit4-audit.yml
    Documentationtype:docs3-task.yml
  4. Write the title.
    • Imperative, no prefix or brackets, no final period, understandable months later: Unify accounts by email.
    • Bug: the symptom is accepted: The QR does not validate offline.
    • Audit: the format AGENTS.md sets for audit titles (Audit <area>: <finding>; the Spanish form Auditoría <área>: <hallazgo> is still accepted).
  5. Pick the rest of the labels (only from labels.yml):

    • area: — 1 or 2, depending on which part of the product it touches. If you are not sure, none.
    • priority: — only if the user gave it or it is obvious (breaks production, money or data → priority:critical). Otherwise, set no priority and add status:triage.
    • business-logic — if it asks to change a rule already defined in an ADR, audit or plan. Cite which one in the body.
    • breaking-change — if it breaks a public contract.

    Assignee: python3 scripts/agents/team.py suggest --labels "<comma-separated labels>" returns who to assign it to according to .github/team.json (by area and load). If it returns nothing, the team is empty: the issue stays unassigned (suggest /add-member). If the user asked for another person, the user wins.

  6. Write the body with the sections of the chosen template, as Markdown (## What happens, ## What should happen…). Rules:
    • Links to files with a repo-relative path and, if useful, the line.
    • If it comes from an audit or ADR, the link to the document and the ID of the finding or rule.
    • Never secrets, tokens or real personal data.
    • At the end: _Opened from the chat with Claude Code at the request of @<user>._ ($BK_HUMAN, or gh api user -q .login if it is not set: a GitHub App has no user).
  7. Show the draft and wait for confirmation. Opening an issue publishes content in the repo. Show the title, labels, assignee, body and blockers (#B blocked by #A) of each issue and ask for an explicit "yes". With several issues, show them all together and confirm the batch once.
  8. Create. Write the body to a temporary file so the escaping does not break:
    gh issue create --title "<title>" --body-file <file> \
      --label "type:bug" --label "area:api" --label "status:triage" --assignee "<assignee>"
    Without an assignee, omit --assignee. Optional, only if the user asked for them: --milestone "<name>", --project "<name>".
  9. Sub-issues (link an issue to an epic that already exists; to build a new epic with several issues, use plan-feature):
    child_id=$(gh api repos/{owner}/{repo}/issues/<child_n> -q .id)
    gh api repos/{owner}/{repo}/issues/<parent_n>/sub_issues -X POST -F sub_issue_id=$child_id
  10. Blockers. If there are dependencies, record them after creating all the issues of the batch (the new ones have no number before). See Blockers between issues.
  11. Reply with the link of each issue created and the blockers that were left. If something failed (nonexistent label, permissions), say so with the error; do not retry with other labels without telling.

Audit → issues

When the request is "turn audit X into issues":

  • One issue per finding, with type:audit and the audit title that AGENTS.md sets (Audit <area>: <finding>).
  • The body links docs/development/<audit>.md and the finding ID (AUD-07).
  • If the document has no IDs, propose adding them before opening the issues.
  • After creating them, offer to note the issue number next to each finding in the document.

Blockers between issues

An issue blocked by another cannot be started (or finished) until the other is closed. Example: "Migrate payments to the new table" is blocked by "Create the new payments table". GitHub shows it on both issues ("Blocked by" / "Blocking") and in the Project.

Do not confuse with sub-issues: a sub-issue is a part of the parent's work; a blocker is an order between two pieces of work that may be independent. An epic can have sub-issues that also block each other.

When to mark a blocker

  • The user asks for it ("#30 depends on #25", "X cannot be done until Y").
  • When creating a batch where the order is obvious (schema before migration, API before the screen that consumes it). In that case propose it in the draft; do not mark it without confirmation.
  • Do not mark it just because two issues touch the same area.

How

Dependencies use the internal id of the blocking issue (not the number):

# #B becomes blocked by #A
id_a=$(gh api repos/{owner}/{repo}/issues/<A> -q .id)
gh api repos/{owner}/{repo}/issues/<B>/dependencies/blocked_by -X POST -F issue_id=$id_a

# See what blocks #B and what #A blocks
gh api repos/{owner}/{repo}/issues/<B>/dependencies/blocked_by -q '.[] | "#\(.number) \(.state) \(.title)"'
gh api repos/{owner}/{repo}/issues/<A>/dependencies/blocking  -q '.[] | "#\(.number) \(.state) \(.title)"'

# Remove the blocker
gh api repos/{owner}/{repo}/issues/<B>/dependencies/blocked_by/$id_a -X DELETE

Also:

  • When blocking an open issue by another open one, add the status:blocked label and a line at the end of the body: Blocked by #A: <why>. The .github/workflows/unblock.yml workflow removes the label on its own when all its blockers are closed.
  • If the blocking one is already closed, the blocker makes no sense: say so instead of creating it.
  • No cycles. Before creating B blocked by A, check that A is not blocked (directly or indirectly) by B, walking A's blocked_by. If there is a cycle, do not create it and explain it.
  • For blockers on existing issues (not just created), show the change (#B blocked by #A) and ask for confirmation as when creating an issue.
  • If the API answers 404 or 422 (repo without dependencies enabled, issue from another repo without permission), say so with the error and leave the blocker written in the issue body as a fallback.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.