GitHub Loop Engineering Skill

The GitHub-native control plane for Loop Engineering.

An Agent Skill that turns GitHub Issues and GitHub Projects into durable state, evidence, and handoff for repeatable agent work—all through the official GitHub MCP Server.

Loop Engineering is about designing the repeatable system around an agent: what it discovers, which bounded transition it attempts, how the result is verified, what gets persisted, and when the loop continues or stops. This skill applies that discipline to the work lifecycle.

flowchart LR
    D["Discover state"] --> F["Frame transition"]
    F --> A["Act once"]
    A --> V{"Verify evidence"}
    V -->|Pass| P["Persist state"]
    V -->|Fail or partial| R["Recover or stop"]
    R --> D
    P --> N{"Continue?"}
    N -->|Next bounded step| D
    N -->|Done or human gate| S["Stop and hand off"]

Loading

The project board as loop memory

GitHub is more than the task list in this loop:

Loop stage	What the skill does	Durable artifact
Discover	Read live repository, issue, hierarchy, Project fields, and policy	Current world state
Frame	Define one authorized transition and the evidence that would prove it	Acceptance criteria and target state
Act	Make the smallest MCP mutation in dependency order	Issue or Project change
Verify	Re-read the affected resources instead of trusting the write response	Observed state and validation evidence
Persist	Record decisions, blockers, validation, and completion	Body, comments, fields, and links
Continue or stop	Route a bounded next step or stop at completion, ambiguity, or a human gate	Follow-up, handoff, or verified done state

The result is an evidence-gated lifecycle: an agent cannot turn “I changed it” into “Done” without a read-back and proof.

Why this skill

• Cold-startable: every issue passes a cold-start check, so a new collaborator or a fresh agent session can act on it without chat history.
• Parallel by design: a parent issue's sub-issues and blocked-by dependencies form a work graph. Any agent can take the parent, query the children that can start now, and hand them to parallel agents.
• Loop-native: every mutation is one pass through discover, frame, act, verify, and persist.
• Evidence-gated: acceptance criteria and current read-back state control lifecycle transitions.
• Durable: GitHub Issues and Projects carry context across agents, sessions, and human handoffs.
• Assignment at start: issues are created unassigned. The agent asks whether to assign the user when work starts, unless the request or repository policy already decides.
• Agent-first triage: agents set Priority when they create an issue and move accepted work out of intake by best judgment, unless repository guidance reserves triage for humans.
• Two review lanes: every pull request is labeled review:human or review:ai. A human reviews interface and UX changes and anything that isn't clearly mergeable. An agent merges the rest only after green CI, an audited pre-commit review of every commit, evidence for every acceptance criterion, and its own rerun of the checks in a clean checkout.
• MCP-first: no gh CLI, curl, direct REST calls, or handwritten GraphQL, except user-authorized fallbacks for the two writes the official server lacks: native issue dependencies and milestones.
• Host-portable: the skill is standard Agent Skills content with no vendor-specific agent metadata. The Claude Code plugin is an optional wrapper that installs the same files unchanged.
• Repository-agnostic: no hard-coded owner, project number, field ID, or option ID. Existing repository vocabulary always wins. A baseline vocabulary applies only when the user authorizes first-use initialization.
• Recoverable: partial failures trigger a fresh read and bounded recovery, never blind replay.
• Honest about limits: missing tools, permissions, or authority become explicit stop conditions.

What it manages

• first-use initialization of labels, issue templates, the Project board, and its automations;
• issue templates that stay current with the skill after installation;
• cold-startable issue creation, triage, assignment, priority, and status;
• project item attachment and custom field updates;
• sub-issue decomposition into parallel work graphs, with dependencies and hierarchy verification;
• fan-out of a parent issue's ready children to parallel agents;
• blockers, implementation notes, and PR/commit references;
• pull request review lanes, and an evidence-gated merge for clearly mergeable pull requests;
• evidence-backed acceptance criteria;
• bulk changes paced under GitHub's rate limits;
• completion, follow-up routing, and human handoff.

This is the lifecycle control and memory layer, not a coding-agent runtime. When a host can run agents in parallel, the skill decides which issues are ready, tells the host what to hand to each agent, and verifies every result on GitHub; the host launches the agents and their workspaces. The skill runs code only to recheck a pull request in a clean checkout before merging it, and it merges only review:ai pull requests that pass the merge gate. It bypasses a missing MCP capability only through the user-authorized fallbacks in the MCP reference. Initialization and template updates go through pull requests that a human merges. Board fields, workflows, and issue types need the GitHub UI, so the agent hands those steps to the user.

Contents

Path	Purpose
skills/github-loop-engineering-skill/SKILL.md	Core loop, lifecycle rules, and safety contract
skills/github-loop-engineering-skill/references/github-mcp-tools.md	Official GitHub MCP tool map and payload patterns
skills/github-loop-engineering-skill/references/work-item-format.md	Cold-start contract and check, plus issue, blocker, note, and completion formats
skills/github-loop-engineering-skill/references/initialization.md	First-use detection, authorization gate, and baseline for labels, board, automations, and templates
skills/github-loop-engineering-skill/references/issue-templates.md	How the skill installs issue templates and keeps them current
skills/github-loop-engineering-skill/references/pull-requests.md	Pull request review labels, classification, merge gate, and post-merge checks
skills/github-loop-engineering-skill/assets/issue-templates/	Cold-start issue templates (en, zh-TW) that initialization installs into .github/ISSUE_TEMPLATE/
.claude-plugin/plugin.json	Claude Code plugin manifest and release version
.claude-plugin/marketplace.json	Single-plugin Claude Code marketplace catalog
scripts/	Bun and TypeScript repository checks (development only)
CHANGELOG.md	Release history

Bootstrap the GitHub MCP dependency

This skill has one runtime dependency: the official github/github-mcp-server.

If it is not connected, ask the agent to bootstrap it:

Install or connect the official github/github-mcp-server for this MCP host.
Use the host's supported installation method, keep credentials out of files
and chat, enable the toolsets required by the GitHub Loop Engineering skill, reload
the tools, verify the connection, and then resume the original request.

The agent should perform the setup itself when the host exposes an approved installer, connector manager, or shell workflow. Installation is host-specific: prefer the official remote server when supported; otherwise use the official container or binary instructions. Do not assume that cloning the source repository configures an MCP host.

Before downloading software, changing user/global host configuration, or starting an authentication flow, the agent must obtain any approval required by the host. Store OAuth or PAT credentials through the host's secret/input mechanism or environment—not in the repository, skill, command transcript, or chat.

Enable at least the issues and projects toolsets. context, repos, labels, and pull_requests are recommended for the full loop:

context,repos,issues,labels,projects,pull_requests

The server's default toolsets (context, issues, pull_requests, repos, users) omit projects and labels, so you must enable them explicitly for board operations. The remote server takes toolsets from the X-MCP-Toolsets header. The local server reads the --toolsets flag or the GITHUB_TOOLSETS variable. Project writes also require project-write authorization. Follow the official server's configuration guide for the detected MCP host.

After setup, verify that identity, issue reads, Project reads, and the requested write tools are actually available. Only then resume the skill at Discover.

Claude Code example

The plugin doesn't bundle an MCP server. That keeps credentials out of the plugin and avoids a second GitHub server when one is already connected. To connect the official remote server for your user, export a GitHub token in your shell first. The shell expands it once, and Claude Code stores the result in your user configuration, not in any repository:

claude mcp add --transport http --scope user github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_PAT" \
  --header "X-MCP-Toolsets: context,repos,issues,labels,projects,pull_requests"

To share the setup with a team, commit a project .mcp.json in the target repository. Claude Code expands ${GITHUB_PAT} from each member's environment when it loads the file, so the committed file holds no secret:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}",
        "X-MCP-Toolsets": "context,repos,issues,labels,projects,pull_requests"
      }
    }
  }
}

Run /mcp to confirm the connection, and approve the project server when Claude Code prompts.

Install

Claude Code plugin

This repository is also a Claude Code plugin marketplace. In a Claude Code session:

/plugin marketplace add Ruisi-Lu/github-loop-engineering-skill
/plugin install github-loop-engineering@github-loop-engineering

Or from your shell:

claude plugin marketplace add Ruisi-Lu/github-loop-engineering-skill
claude plugin install github-loop-engineering@github-loop-engineering

Run /reload-plugins or start a new session to load it. The plugin pins its release version, so a new release reaches you only after the version changes. Third-party marketplaces don't auto-update by default. Enable auto-update in the /plugin Marketplaces tab, or update manually:

claude plugin marketplace update github-loop-engineering
claude plugin update github-loop-engineering@github-loop-engineering

To enable the plugin for everyone who works in a repository, commit this to that repository's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "github-loop-engineering": {
      "source": {
        "source": "github",
        "repo": "Ruisi-Lu/github-loop-engineering-skill"
      }
    }
  },
  "enabledPlugins": {
    "github-loop-engineering@github-loop-engineering": true
  }
}

Other Agent Skills hosts

With an Agent Skills-compatible installer:

npx skills add Ruisi-Lu/github-loop-engineering-skill

Or copy the skill directory into the location used by your agent:

cp -R skills/github-loop-engineering-skill ~/.codex/skills/

For a standalone Claude Code skill without the plugin wrapper:

cp -R skills/github-loop-engineering-skill .claude/skills/

Install either the plugin or a standalone copy in Claude Code, not both. With both, the same skill loads twice under different names.

Restart or reload the agent host if it does not discover newly installed skills automatically.

Use

The skill triggers automatically when a request matches its description. To invoke it explicitly:

Host	Invocation
Claude Code plugin	/github-loop-engineering:github-loop-engineering-skill
Claude Code standalone skill	/github-loop-engineering-skill
Codex	$github-loop-engineering-skill

Run one bounded work loop:

Use the GitHub Loop Engineering skill to inspect issue #42 and its project item,
choose the next authorized transition, apply it, verify it, and persist the evidence.

Create and route work:

Use the GitHub Loop Engineering skill to create an issue for the failing upload
retries, add it to our engineering project, set the existing priority to High,
and verify every resulting state.

Enforce a completion gate:

Use the GitHub Loop Engineering skill to close issue #42 only if every acceptance
criterion has current evidence, then synchronize and verify the project status.

Work through a parent issue in parallel:

Use the GitHub Loop Engineering skill to work through epic #40. Hand every child
that can start now to its own agent in a separate worktree, verify each result on
GitHub, and keep going until the epic is done or needs me.

Merge a clearly mergeable pull request:

Use the GitHub Loop Engineering skill to check PR #128. If it is labeled review:ai
and passes the merge gate, merge it, then verify that its issues closed and the
board moved them to Done.

Initialize a repository on first use:

Use the GitHub Loop Engineering skill to set up this repository's issues and board
for the first time. Propose the labels, Project fields, automations, and zh-TW
issue templates, apply what I approve, and list the steps I must do in the UI.

The skill follows repository instructions and existing project vocabulary. Ambiguous targets, insufficient evidence, missing capabilities, and new authority requirements stop the loop before an unsafe transition.

Design boundaries

The skill targets the official GitHub MCP Server's documented tool surface. It never silently switches to a CLI or direct API: it uses the GitHub CLI's API client only for native issue dependencies and milestones, which the server can't write yet, and only after the user authorizes it. Arbitrary project configuration remains conditional on the tools exposed by the connected server.

Each agent completes one lifecycle operation or bounded recovery at a time. Fanning out a parent issue coordinates many such loops: the skill decides what is ready and verifies the results, while the host provides the agents and their isolated worktrees. Writing code, deployment, and unattended repetition belong to the surrounding Loop Engineering harness.

Agents merge only review:ai pull requests, and only after the merge gate passes on the exact head commit. The skill doesn't count on branch protection or required checks, because private repositories on GitHub Free have neither. The gate is the only enforcement, so the merging agent checks every condition itself.

The Claude Code plugin packages only the skill. It adds no hooks, agents, commands, or MCP servers, so installing it grants no new tool access.

Development

The toolchain is pinned in .prototools and managed with proto. The repository checks live in scripts/ so the plugin root never pairs a package.json with a lockfile. Claude Code would otherwise install those development dependencies for every plugin user.

proto install
cd scripts
bun install --frozen-lockfile
bun run check

bun run check type-checks the scripts. It then verifies that the marketplace entry matches plugin.json, that the latest CHANGELOG.md release matches the plugin version, that skill frontmatter is valid, and that relative Markdown links and anchors resolve. It finishes with claude plugin validate --strict, which is skipped with a warning locally when the Claude Code CLI is absent and required in CI.

To release:

1. Move the Unreleased changelog entries into a new version section.
2. Set the same version in .claude-plugin/plugin.json. Leave version out of marketplace.json, because plugin.json is the single source of truth.
3. Run bun run check, then commit.
4. Run claude plugin tag . --push to create and push the github-loop-engineering--v<version> tag.

License

MIT — see LICENSE.