GitHub

Every agent does GitHub work the same way: formats come from the repository's .github/ folder, commands from the files below. Do not improvise a format, label or command they already define. What to do and when comes from create-issue and create-pr.

Rules

• Read repository policy and settings. Start with the project's instructions, which may name the board and its statuses. Resolve the integration branch, merge method, labels, milestones and issue-script alias from contribution guidance, repository settings and .github/. When no integration branch is specified, use the default branch: gh repo view --json defaultBranchRef --jq .defaultBranchRef.name.
• Ask before you publish, unless the user asked for that exact action, or the board mapping already approves the move. Pushing, creating or editing issues and PRs, commenting and merging all publish.
• A board is optional. Follow Board.
• Offer to record the board. When you had to ask which board or statuses, offer to add them to the project's instructions so the next agent reads them. Edit that file only after the user agrees.
• Issues come from draft files. Write a draft and run the issue script below. Never call gh issue create by hand: the script validates the draft against the issue forms and labels, then sets the type, labels, milestone, parent and "blocked by" links.
• The schema is in .github/. The forms in .github/ISSUE_TEMPLATE/ define each kind of issue and its sections. .github/labels.yml, when present, lists the allowed labels. .github/pull_request_template.md is the PR body. Read them; do not restate them.
• Commit forms before filing. When the script reports no issue forms, or before opening a PR when .github/pull_request_template.md is missing, ask the user to choose: install the defaults with --init, then review and commit them; copy in forms or a template the project already keeps elsewhere, such as the account's .github repository; or stop. The script reads only the repository's own .github/, and committed forms give people who file on github.com the same sections as agents.
• Use scratch files outside the tree for drafts and PR bodies, so they are never committed.
• Never put a token on the command line, force-push the integration branch or someone else's branch, or link a local or gitignored file from an issue or PR. Stack branches are rewritten only through gh stack, which pushes with --force-with-lease.

References

Board

A GitHub Project linked to the repository is a board. With none, skip it. With one, use it; with several, ask which.

1. Unless the project's instructions give the statuses, list the status options (cli.md: Board) and ask once which option is in progress, which is in review, and which is done. Skip a step the user leaves unset. That answer approves the later moves.
2. Add the issue if it is not on the board, before the first status move.
3. Read the current status (cli.md: Board). Set in progress before implementation starts, and assign the logged-in user (cli.md: Issues), so other agents see the issue is taken. Set in review when its PR opens, and done when that PR merges, not when work on the issue finishes.

Script

scripts/create-issues.mts validates drafts and, with --apply, creates them. Run it from inside the repository with Node 22.6 or later, or through the project's alias when it has one:

node --experimental-strip-types <this skill's folder>/scripts/create-issues.mts <file.md | folder> [more files] [--repo owner/name] [--apply]

Without --apply it only validates and prints what it would create, with each issue's labels and milestone. <issue script> in the references means this command.

node --experimental-strip-types <this skill's folder>/scripts/create-issues.mts --init [--repo owner/name]

--init copies the default forms (bug, task, tracking, decision), labels and pull request template from assets/ into .github/, and prints what it wrote. A form keeps its issue type only when the repository has that type: organizations define issue types, and a personal repository has none. It keeps an existing labels.yml and pull request template, refuses to overwrite an existing form, and never commits.