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:
- AI Agent landscape knowledge — domain topics, known repos, ecosystem map
- AI-specific discovery patterns — MCP, A2A, agent-framework search rounds
- AI-domain difficulty rubric — adapted to LLM/agent/protocol issue patterns
- 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
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 framework", "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", "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", "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-fixeror the domain-specific skill - User explicitly requests the generic
issue-fixerflow - 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
ghbefore 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 Protocol | anomalyco/opencode, different-ai/openwork | opencode, coding-agent |
| PI Ecosystem | 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:
gh auth status # GitHub CLI authenticated
git --version # Git available
Refuse to work directly on main. Read repo instruction files before touching code.