bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
agent-orchestrator/skills
History
i-trytoohard 0133bcdc88
chore: add bug-triage skill for agent-driven issue triage (#1725) 
* 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>
 		2026-05-12 20:51:00 +05:30
..
agent-orchestrator feat(windows): complete Windows support (#1025) 2026-05-09 00:10:53 +05:30
bug-triage chore: add bug-triage skill for agent-driven issue triage (#1725) 2026-05-12 20:51:00 +05:30
release-notes/ao-weekly-release feat(skills): add ao-weekly-release skill for automated release notes (#1239) 2026-04-23 01:11:31 +05:30
social-media feat(skills): add social-media-posts skill for X and LinkedIn (#1498) 2026-04-26 17:48:29 +05:30
README.md chore: add bug-triage skill for agent-driven issue triage (#1725) 2026-05-12 20:51:00 +05:30

README.md

Skills

Reusable skill documents for AI coding agents working on this repository. Each skill is a self-contained SKILL.md that teaches an agent how to perform a specific task.

Available Skills

Skill Description
bug-triage/ Triage bugs reported in chat/issues — investigate, search duplicates, file GitHub issues, push fix PRs
agent-orchestrator/ Architecture and conventions for working on the agent-orchestrator codebase
release-notes/ Generate weekly release notes from git history
social-media/ Social media post generation

How to Use

Copy the skill into your coding agent's skill directory. The destination depends on which agent you're using:

Claude Code

cp -r skills/bug-triage .claude/skills/bug-triage

Or add the full path to your CLAUDE.md:

See skills/bug-triage/SKILL.md for bug triage workflow.

OpenAI Codex CLI

cp -r skills/bug-triage .codex/skills/bug-triage

Or reference in AGENTS.md:

See skills/bug-triage/SKILL.md for bug triage workflow.

Cursor

Add to .cursor/rules/ as a rule file:

cp skills/bug-triage/SKILL.md .cursor/rules/bug-triage.mdc

Windsurf / Other Codeium-based agents

Add to .windsurf/rules/:

cp skills/bug-triage/SKILL.md .windsurf/rules/bug-triage.md

GitHub Copilot

Add to .github/copilot-instructions.md or reference in .github/:

cp skills/bug-triage/SKILL.md .github/skills/bug-triage.md

Gemini CLI

cp -r skills/bug-triage .gemini/skills/bug-triage

Agent Orchestrator (this project)

Skills in this skills/ directory are automatically available to agents spawned via ao spawn. Reference them in AGENTS.md or CLAUDE.md so agents load them at the start of a session.

Writing a New Skill

  1. Create a directory under skills/<name>/
  2. Add a SKILL.md with YAML frontmatter:
---
name: my-skill
description: One-line description of what the skill does.
trigger: When to activate this skill.
---
  1. Write the skill body in markdown — numbered steps, code blocks, tables
  2. Keep it agent-agnostic: use gh CLI, git, and standard Unix tools. Avoid tying to a specific agent framework
  3. Reference it in AGENTS.md so spawned agents discover it