* chore: add bug-triage skill for agent-driven issue triage
Add .skills/bug-triage/ with SKILL.md and push_fix_to_github.py script.
The skill provides a complete triage workflow:
- Gather bug context from chat/issues/live observation
- Search for duplicate GitHub issues
- File well-structured issues with root cause analysis
- Push fix PRs via GitHub API (no local checkout needed)
- Git archaeology (git log -S) for regression tracking
- NPM package regression diffing
- Remote code inspection without local clone
Reference the skill in AGENTS.md so any agent working on this repo
can discover and follow the triage workflow automatically.
Tested across 100+ real bug triages on ComposioHQ/agent-orchestrator.
* chore: add clickable issue/PR links as real-world examples
Add concrete examples with links to actual issues and PRs:
- #1129: deep diagnosis vs surface-level triage
- #1151: placeholder URL RCA
- #1391: CSS regression via git log -S archaeology
- PR #1523: optional TypeScript interface fields
- PR #1608: npm package regression diffing
* chore: add formatting rule — always linkify issue/PR references
Any agent following this skill must include clickable URLs when
mentioning issues or PRs. Bare '#123' without links is not allowed.
* fix: address review feedback — use existing skills/ dir, fix bugs
- Move .skills/ → skills/ (repo already has a skills/ directory)
- Fix label name: 'priority:medium' → 'priority: medium' (with space)
- Fix issue-assets branch naming: use slug instead of issue number
(issue doesn't exist yet at upload time)
- Fix base64 command: portable across Linux and macOS (tr -d '\n')
- push_fix_to_github.py: allow empty NEW_STRING for deletion edits
- push_fix_to_github.py: warn on multiple OLD_STRING matches
- push_fix_to_github.py: create branch before fetching file (SHA race)
- push_fix_to_github.py: configurable BASE_BRANCH (not hardcoded main)
- Update all path references in AGENTS.md and SKILL.md
* fix: correct stale .skills/ path in AGENTS.md How to load section
* feat: add cross-platform triage awareness (Windows/macOS/Linux)
Add Step 1b covering:
- When to ask for OS/shell/runtime/reproducibility
- Common Windows-specific bug patterns (paths, shell syntax, ConPTY,
named pipes, NTFS case-insensitivity, localhost IPv6 stalls)
- Key cross-platform files (platform.ts, CROSS_PLATFORM.md, etc.)
- Tagging OS-specific issues with 'to-reproduce'
Based on the actual Windows support implementation in #1025
(platform.ts, runtime-process, CROSS_PLATFORM.md).
* feat: add 6 triage improvements from real failure patterns
1. Environment Info Collection (Step 1):
- Standard template: OS, shell, runtime, AO version, Node version, install method
- Prevents wasted time tracing wrong code versions
2. Duplicate Search Strategy (Step 2):
- Search by symptom, component, AND error message
- Always search --state all (open + closed — bugs regress)
- Check PRs too (fixes sometimes land without issues)
3. Stop-and-Ask Triggers (Step 1c):
- Explicit criteria: 3 failed hypotheses, can't reproduce, upstream bug,
UI-only bug without screenshot, unknown environment
- Includes template for asking the reporter
4. Pre-Submission Checklist (Step 4.1b):
- Reporter attribution, commit hash, AO version, confidence score,
cross-links, concrete reproduction steps, screenshots ready
- Verify all before creating the issue
5. Confidence Scoring (Step 4.4):
- High/Medium/Low with clear criteria
- Maps to labels: bug only / to-explore / to-reproduce
- Example from PR #1608 where high confidence was wrong
6. Cross-Linking Related Issues (Step 4.5):
- Search by subsystem after filing
- Include Related section with one-line descriptions
- Helps maintainers see patterns across issues
7. Subsystem-Specific Triage Quick Reference:
- Table mapping subsystems to required info and key files
- Common misrouting patterns (terminal, stuck session, config)
* feat: add report gate, local diagnostics with ao events, deduplicate
New sections:
- Step 0a: Platform-specific context gathering (Discord/Slack/GitHub/live)
- Step 0b: Minimum Viable Report Gate — required fields (what/where/when)
plus 2-of-4 supporting (OS, version, reproducibility, steps)
- Step 0c: Local Diagnostics — auto-gather environment, process health,
AO event log (ao events list/search/stats), session state files,
reproducibility testing. Covers ao events commands with all flags.
Deduplication:
- Step 1b: removed repeated OS/shell/runtime questions (now in Step 1.2)
- Step 1c: removed 'environment unknown' and 'can't reproduce' triggers
(covered by report gate in Step 0b)
* refactor: compress bug-triage skill from 575→311 lines
Merge overlapping sections (Steps 0/0b/0c/1 → single Gather+Investigate flow),
move reference material to Appendix, deduplicate pitfalls, compress code blocks.
All factual content preserved: commands, file paths, labels, examples, links.
* docs: add skills/ README with agent-specific install instructions
Covers Claude Code, Codex CLI, Cursor, Windsurf, Copilot, Gemini CLI,
and Agent Orchestrator. Includes available skills table and how to write
new skills.
* docs: add Skills section to CLAUDE.md referencing skills/ directory
Links all 4 skills with when-to-load guidance, plus pointer to
skills/README.md for installing into other agents.
* fix: resolve PR review comments — remove Hermes-specific refs, portable base64
- Replace execute_code references with agent-agnostic 'Python script' wording
- Replace base64 -d (Linux-only) with python3 -c (portable across macOS/Linux/Windows)
---------
Co-authored-by: AO Bot <ao-bot@composio.dev>
0133bcdc88