AGENT SKILL

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 12
Forks
5

01 前言 Front Matter

name
mergecraft
description
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
compatibility
Requires uv; gh CLI optional

03 SKILL.md 正文

mergeCraft

mergeCraft is an AI-powered PR reviewer: a GitHub Action plus a Python CLI (mergecraft). BYOK — the user's Claude/ChatGPT subscription or API key; no SaaS backend. Deterministic analyzers run first, then an LLM review agent, then a read-only verifier; typed findings drive inline comments and the mergecraft-approval commit status.

Setup checklist (new consumer repo)

  1. Prereqs: <!-- BEGIN:requirements --> Requirements: uv is the only prerequisite for the install; it downloads a compatible Python (3.11+) itself, so no system Python is needed. The GitHub CLI (gh auth login) is needed only for provider auth --scope github (the default) or --scope both, which stores the secret with gh secret set. mergecraft init needs neither gh nor a network; --scope local needs no gh, but provider-specific authentication may need a network. Two providers need one more CLI at the credential step: the Codex CLI for openai and Claude Code for anthropic (provider table). <!-- END:requirements --> If uv cannot be installed, use the Docker Action only (docs/install.md).

  2. Install:

    uv tool install mergecraft-action==0.1.0a6
    mergecraft init
    

    Docs on main may describe unreleased behavior. Use the matching release docs for this install; do not assume newer CLI flags or fixes are included.

  3. Authentication — STOP and ask the user. Use mergecraft provider list to find the configured provider label or id from init. Authenticate that entry with mergecraft provider auth <label-or-id> --scope local for local evaluation, or --scope github to adopt GitHub Actions. Examples below assume these provider labels are configured:

    • mergecraft provider auth opencode --scope github (OpenCode Zen, billing-backed key)
    • mergecraft provider auth opencode-go --scope github (OpenCode Go subscription)
    • mergecraft provider auth openai --scope github (ChatGPT Plus/Pro/Team/Enterprise)
    • mergecraft provider auth anthropic --scope github (Claude Pro/Max)
    • mergecraft provider auth google --scope github (Google AI Studio)
    • API-key providers: mergecraft provider auth deepseek|minimax|tokenhub|openrouter|xai --scope github

    Never handle raw credentials; never commit secrets. GitHub scope checks the exact target repository before collecting credentials, stores Actions secrets, and rewrites .github/workflows/mergecraft.yml so the workflow passes them. Local scope writes only the displayed .env file and never calls GitHub. After auth, run mergecraft doctor: its workflow auth row must be ok (if not, run mergecraft workflow sync --apply).

  4. Commit .mergecraft/config.yaml, .mergecraft/learnings.md, .github/workflows/mergecraft.yml, and any .gitignore lines init added; push; open a PR or run workflow_dispatch. The default workflow does not listen for @mergecraft review comments.

Standalone installation links

Install the generated skills/<harness>/mergecraft/SKILL.md package. The raw skills/mergecraft/SKILL.md is a generator template; replace a copied template with the generated package to repair relative links. Documentation links use the v0.1.0a6 release tag, the release this checklist installs. Release maintainers can set MERGECRAFT_AGENT_PACKAGES_REF when generating packages for another verified ref. Fetch that ref first: an unresolved explicit override fails instead of silently substituting a branch.

CLI quick reference

Command Purpose
mergecraft init Scaffold config + workflow
mergecraft review Review local diff / branch changes (primary local review command)
mergecraft review --dry-run Print prompt, no LLM call
mergecraft review --json out.json Machine-readable findings
mergecraft provider auth … --scope github Interactive provider login → gh secret set
mergecraft models list|show|set Inspect/configure model chains
mergecraft analyzers list|detect|run|explain Deterministic analyzers
mergecraft learnings active|staging Inspect learnings memory
mergecraft findings export Export unresolved findings
mergecraft mcp serve Start MCP HTTP server (Bearer token required)
mergecraft mcp list List MCP tool surface for a role

diff-review is a deprecated alias for mergecraft review (one stderr warning per invocation) — teach mergecraft review instead.

MCP

Two profiles — do not confuse them:

Profile Command Transport Auth
Public product mergecraft mcp serve --role public --transport stdio stdio JSON-RPC None (local OS user)
Runtime harness mergecraft mcp serve (default --role reviewer) HTTP on ephemeral port Per-serve Bearer required

Public install (Cursor, Claude Desktop, Codex, Gemini CLI, OpenCode): see docs/mcp.md for copy-paste mcpServers JSON. Six tools only (review_change, get_review, inspect_finding, explain_finding, get_capabilities, get_policy). Registry: mcp-name: io.github.alexhawat/mergecraft.

Runtime harness HTTP: default mergecraft mcp serve mints a Bearer token on an ephemeral port; omitting Authorization: Bearer … returns HTTP 401 / JSON-RPC -32600. Reviewer tools live at /mcp/reviewer. Startup prints MERGECRAFT_MCP_BEARER=<token> to stderr — pass that token on every HTTP request. Optional HTTP public (--role public without --transport stdio) also requires Bearer.

Configuration essentials (.mergecraft/config.yaml)

  • models: ordered fallback chain, e.g. ["anthropic/claude-sonnet", "openai/gpt-5.3-codex"]. Uncredentialed providers are skipped; transient failures fall through. model_pin: enabled opts out.
  • prApproveEnabled: true lets trusted-tier runs submit a real APPROVE.
  • Trust tiers are fail-closed: fork PRs and pull_request_target run with no secrets/network — do not "fix" this.
  • Learnings in .mergecraft/learnings.md: new entries land in ## Staging; only maintainer-associated authors promote to ## Active.

Troubleshooting

  • mergecraft-approval failing/neutral — pure function of typed findings; run mergecraft findings export and read blocking items. Prose verdict cannot override a blocker.
  • Workflow did not trigger on comment — only OWNER/MEMBER/COLLABORATOR commenters are authorized; authorization reads author_association from the event payload, never the comment body.
  • Model skipped — no credential for that provider; run mergecraft models list.
  • Full docs: README.md, AGENTS-mergecraft.md, docs/REVIEW-CHECKS.md, docs/.

04 同仓库更多 Skills

alexhawat
alexhawat/mergeCraft

git-archaeology

Investigate how code reached its current state — when a line, function, import, or whole file was changed or deleted, who removed it, and what it looked like before. Use when `git blame` came up empty, when content has been refactored away, or when you need the full evolution of a function across commits.

★ 12
alexhawat
alexhawat/mergeCraft

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

★ 12
alexhawat
alexhawat/mergeCraft

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

★ 12
alexhawat
alexhawat/mergeCraft

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

★ 12
alexhawat
alexhawat/mergeCraft

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

★ 12
alexhawat
alexhawat/mergeCraft

mergecraft

Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.

★ 12