# AI Agent Fixer

> Use when fixing issues in AI-related repositories.

- Skill: `re2zero/ai-agent-fixer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add re2zero/ai-agent-fixer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/re2zero/ai-agent-fixer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: re2zero (https://skillmd.com/u/re2zero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/re2zero/ai-agent-fixer

---


# AI Agent Fixer

## Overview

A domain-specialized variant of **issue-fixer** for the AI Agent / AI
Specification open-source ecosystem. Inherits the full 3-workflow lifecycle
(Fix / Discover / Track) from issue-fixer. This skill **adds**:

1. **AI Agent landscape knowledge** — domain topics, known repos, ecosystem map
2. **AI-specific discovery patterns** — MCP, A2A, agent-framework search rounds
3. **AI-domain difficulty rubric** — adapted to LLM/agent/protocol issue patterns
4. **AI quality signals** — commit freshness, spec compliance, issue responsiveness

**REQUIRED BASE SKILL:** You MUST load and reference `issue-fixer` for the core
workflow (A1–A6, B1–B3, C0–C2). This skill only overrides domain-specific parts.
Do not re-derive the general workflow — the base skill defines it.

## When to Use

```mermaid
flowchart TD
    A["用户输入"] --> P1{"含 AI Agent 关键词?<br/>agent / MCP / A2A / LLM<br/>--discover agent-*"}
    P1 -->|yes| B["Call ai-agent-fixer<br/>→ AI Agent discover mode"]
    P1 -->|no| P2{"已经是 issue-fixer 流程<br/>但仓库是 AI 域?"}
    P2 -->|yes| B
    P2 -->|no| C["回退到 issue-fixer<br/>通用流程"]
```

### Input → Workflow routing

| Input | Route |
|-------|-------|
| `--discover <domain>` | Workflow B, AI discovery (domain table below) |
| `--org <ORG>` | issue-fixer B2 (organization discovery) |
| `owner/repo#N` | issue-fixer A1 → A2; if AI domain, apply AI rubric |
| `PR-URL` / `--track <PR>` | issue-fixer C0; if AI domain, apply C1 context |
| AI keywords without flags (MCP, A2A, agent, LLM, SDK, framework) | Auto-detect domain (below) → Workflow B |
| `langchain-ai/langchain`, `modelcontextprotocol/servers#42`, `anomalyco/opencode` | AI domain — apply AI-specific rules |
| Nothing AI-related | Fall back to issue-fixer generic workflow |

### Keyword → AI domain

| User says | Domain | Reference |
|-----------|--------|-----------|
| "AI Agent框架", "agent framework" | `agent-framework` | repo-discovery §agent-framework |
| "MCP", "Model Context Protocol" | `mcp` | repo-discovery §MCP |
| "A2A", "Agent-to-Agent" | `a2a` | repo-discovery §A2A |
| "opencode", "coding agent", "编码代理" | `opencode` | repo-discovery §opencode |
| "AI SDK", "Agent SDK" | `agent-sdk` | repo-discovery §SDK |
| "pi", "pi coding agent" | `pi` | repo-discovery §pi |
| "orchestrate", "orchestration", "编排" | `agent-orchestration` | repo-discovery §orchestration |
| No domain | `coding-agent` (default) | repo-discovery §default |

## When NOT to Use

- Repo is not AI-related (Linux desktop, embedded, plain web) — use `issue-fixer` or the domain-specific skill
- User explicitly requests the generic `issue-fixer` flow
- AI keywords appear only incidentally (e.g. "LLM" in a blog title) with no AI contribution intent
- Task is local-only (no GitHub discovery/fix/PR) — no skill needed

## Quick Reference

| Need | Where |
|------|-------|
| Route decision | When to Use tables above |
| `--discover` search commands | `references/repo-discovery.md` §Domain Templates |
| Verify repo freshness | repo-discovery §Known-Active Issue Hunt (script) |
| Difficulty scoring | `references/difficulty-analysis.md` §Scoring |
| Forced escalation rules | difficulty-analysis §Forced Escalation |
| Fix / PR workflow | issue-fixer Workflow A (A1–A6) |
| PR tracking loop | issue-fixer Workflow C (C0–C2) |

## Workflow B: AI Agent Discovery (overrides issue-fixer B)

### B0. Domain detection

Use the Keyword → AI domain table in When to Use. Parse the user's intent into
an AI Agent domain, then apply that domain's search template.

### B1. AI repo discovery

Use domain templates from `references/repo-discovery.md`. Round-based
broadening: start with high-specificity topics, relax to broader AI topics,
then fall back to keyword search.

**Key differences from generic issue-fixer B1:**
- Star thresholds are **lower** (50–100 instead of 200–500) — AI ecosystem is young
- Primary languages are **Python and TypeScript** (not C/Go/Rust)
- Keywords use AI domain vocabulary: `model-context-protocol`, `a2a`,
  `ai-agents`, `agent-framework`
- Quality signals prioritize **commit recency** and **issue response time**
  over raw star count
- Repo lists in the reference are **snapshots** — verify freshness with `gh`
  before trusting them

### B2. AI-specific difficulty analysis

Use `references/difficulty-analysis.md` for AI-domain scoring.
Key patterns that score **Easy** in AI repos:
- Tool description typos / grammar fixes
- Missing Pydantic field validators
- README / documentation gaps (very common in fast-moving AI repos)
- Import path fixes after refactor
- Missing error handling on API calls
- Type annotation corrections

### B3. Common AI issue types

| Issue type | Difficulty | Typical fix |
|------------|-----------|-------------|
| Tool description typo | Easy (4-5) | Edit string in tool definition |
| Missing error handling | Easy (4-6) | Add try/except around LLM call |
| Pydantic validation | Easy (5-6) | Add field validators |
| README improvement | Easy (4-5) | Write clear docs |
| Import path fix | Easy (4-5) | Update module import |
| Missing env var support | Moderate (6-7) | Add config with safe default |
| Streaming edge case | Moderate (7-8) | Handle partial chunk |
| Tool schema correction | Moderate (7-8) | Fix JSON schema |

See `references/difficulty-analysis.md` for the full rubric.

## Workflow A & C

**Inherited from issue-fixer** with these AI-domain-specific adjustments:

### A4. AI-domain analysis notes

When analyzing AI Agent issues, pay attention to:
- **Non-deterministic behavior** — LLM responses vary; distinguish deterministic
  bugs from model behavior variance
- **API version compatibility** — AI repos depend on fast-moving upstream
  libraries; check pinned versions
- **Async patterns** — most AI Agent code uses `asyncio`; ensure proper
  await/coroutine handling
- **Tool/function schema** — JSON Schema generation for LLM function calling is
  a common pain point

### C1. AI-domain review handling

When tracking AI-domain PRs:
- LLM call patterns and tool integration code often receive maintainer scrutiny
- Pay attention to protocol compliance reviews (MCP init sequence, A2A card
  exchange)
- Async error handling in agent loops is a frequent review topic
- Understand MCP protocol lifecycle: `initialize` → `list tools` → `call tool`
  → `shutdown`

## AI Agent Landscape (Quick Reference)

| Layer | Key Repos | Topics |
|-------|-----------|--------|
| Coding Agent 协议 | anomalyco/opencode, different-ai/openwork | `opencode`, `coding-agent` |
| PI 生态 | earendil-works/pi + community | `pi-coding-agent`, `agent-toolkit` |
| Agent Orchestration | stablyai/orca, getpaseo/paseo, omnigent-ai/omnigent | `agent-orchestration`, `parallel-agents` |
| Frameworks | langchain, langgraph, crewAI, autogen, semantic-kernel, pydantic-ai, agno | `ai-agents`, `agent-framework` |
| Protocols | modelcontextprotocol/specification, google/A2A | `model-context-protocol`, `a2a` |
| SDKs | openai/openai-python, anthropic-sdk | `agents-sdk`, `ai-sdk` |
| Tools | composio, browser-use, mcp-servers | `agent-tools`, `mcp-server` |

**Key AI Topics for Search:** `ai-agents`, `agent-framework`, `llm-agent`,
`multi-agent`, `model-context-protocol`, `mcp`, `mcp-server`, `a2a`,
`agent2agent`, `agents-sdk`, `function-calling`, `tool-use`,
`agent-orchestration`, `opencode`, `coding-agent`, `agentic-coding`

See `references/repo-discovery.md` for full topic tables and search commands.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using generic Linux/C topics instead of AI Agent topics | Load this skill — AI domain topics differ fundamentally |
| Applying too-high star thresholds to young AI repos | Lower threshold to 50-100; focus on commit recency |
| Not recognizing AI Agent keywords in user's request | Auto-detect: agent / MCP / A2A / LLM / SDK / framework |
| Using generic difficulty rubric for AI repos | Load `references/difficulty-analysis.md` AI adaptation |
| Not understanding MCP protocol lifecycle for protocol issues | Read MCP spec: init → list → call → shutdown |
| Treating LLM non-determinism as a bug | Distinguish deterministic bugs from model behavior variance |
| Overlooking Python as dominant language | AI Agent ecosystem is Python-first; TS second |
| Re-deriving issue-fixer workflow | Load base skill — this is a specialization, not a replacement |
| Trusting stale repo snapshots in references | Snapshot lists are candidate starts only — verify with `gh` |

## Safety Guardrails

Same as issue-fixer with two AI-domain additions:

- **No live LLM API calls** — never use real API keys for testing; use mocks/fixtures
- **No model behavior modifications** (prompt changes that affect output quality
  without understanding consequences → escalate)
- **Respect API terms of service** — don't patch rate limits or ToS restrictions
- **Protocol compliance is critical** — MCP/A2A changes must preserve spec compliance
- **All inherited from issue-fixer**: no main commits, no force-push, no test
  deletion, max 15 files, draft PR by default, no AI identification

## Rationalization Table — Why Agents Skip This Skill and Why That Fails

| Excuse | Reality |
|--------|---------|
| "I'll just use issue-fixer's generic discover, AI repos aren't that different" | AI repos have completely different search topics (ai-agents vs linux), lower star thresholds (50-100 vs 200-500), and Python/TS dominance (not C/Go). You'll miss the entire target space. |
| "MCP is just another networking protocol, I'll use the networking template" | MCP has a unique lifecycle (init → list → call → shutdown) and ecosystem (spec + SDKs + servers). Generic protocol templates don't cover this. |
| "This AI repo has low stars so it's not worth contributing to" | The AI agent ecosystem is 1-3 years old. Many high-quality projects have under 200 stars. Judge by commit recency and spec compliance, not star count. |
| "I understand LLMs so I don't need the AI difficulty rubric" | The rubric captures domain-specific patterns (Pydantic validation, tool schema, streaming edge cases). Generic rubric misses these. |
| "I'll test with a real API call, it's faster than setting up mocks" | **FORBIDDEN.** Never make live LLM API calls in tests. This wastes real compute credits and introduces non-determinism. Use fixtures. |
| "The user said 'find issues' — I'll just use generic search" | If the user mentioned any AI Agent keyword (MCP, A2A, agent, LLM, framework, SDK), you MUST route to this skill. Generic search misses AI domain targets. |
| "This is just a documentation fix, AI domain knowledge doesn't matter" | AI repo docs are tightly coupled to rapidly evolving APIs. Without AI domain context, you'll write docs referencing deprecated or nonexistent features. |
| "The reference lists these repos as active, I'll trust the list" | Lists are snapshots from skill authoring time. Star counts and activity drift within weeks. Verify with `gh` before choosing a target. |

## Red Flags — STOP and Route Here

When you catch yourself thinking any of these, you are ABOUT to skip AI Agent domain
specialization. Stop, load this skill, and use AI-specific discovery:

- "I'll just use --topic=linux, it's close enough"
- "Low stars = low quality" (for AI repos)
- "I know enough about LLMs, I don't need the domain rubric"
- "A quick real API call to verify won't hurt"
- "The user didn't say --discover but I'll use generic mode" (if they mentioned AI keywords)
- "I don't need to load issue-fixer, I know the workflow"
- "This AI repo's issues look like any other project's issues"
- "The reference list is fresh enough, no need to verify"

**All of these mean: Stop. Load ai-agent-fixer. Then load issue-fixer for the workflow.**

## Preflight

Same as issue-fixer:

```bash
gh auth status          # GitHub CLI authenticated
git --version           # Git available
```

Refuse to work directly on `main`. Read repo instruction files before touching code.