Agent Skills

ContribFlow ships starter skill docs for agent harnesses. These files are meant to be copied into, referenced by, or adapted for agent environments that need a CLI-first OSS contribution workflow.

Available skills:

• skills/generic-agent/SKILL.md
• skills/codex/SKILL.md
• skills/claude-code/SKILL.md
• skills/oss-contrib-orchestrator/SKILL.md

Recommended default:

• oss-contrib-orchestrator

Agent JSON uses canonical contribflow commands in recommendedCommand. Skills should execute returned commands exactly; cflow is only a human shorthand in examples.

Each skill teaches an agent to:

• verify prerequisites
• install or run the CLI from source
• confirm gh auth
• initialize local config
• ask for contribution preferences
• run discovery
• score candidates
• generate a plan in later milestones
• ask before public GitHub actions
• keep PRs small and maintainer-friendly
• run the full CLI workflow through PR dry-run
• stop before public GitHub writes until explicit approval

Install Skills

For a complete agent-first setup prompt, see docs/AUTONOMOUS_AGENT_QUICKSTART.md.

List available skills:

npm run skills:list

Preview an install without writing files:

npm run skills:install -- --target codex --skill all --dry-run

Install the orchestrator skill for Codex:

npm run skills:install -- --target codex --skill oss-contrib-orchestrator

Install all skills into a custom harness directory:

npm run skills:install -- --dest /path/to/skills --skill all

Use --json when a harness needs structured installer output.

Validate the installer:

npm run validate:skills

See docs/SKILL_DISTRIBUTION.md.

Running From Source

Until packaged distribution exists, agents should run ContribFlow from this repository:

npm install
npm run build:cli
npm run cflow -- --help

When the binary is available on PATH, use cflow or contribflow directly.

Current CLI Commands

cflow init
cflow status --json
cflow discover --json
cflow score owner/repo#123 --json
cflow plan owner/repo#123 --json
cflow checkout owner/repo#123 --json
cflow diff --json
cflow validate --run --sandbox docker --json
cflow pr --draft --json
cflow next --json

Use --json whenever the agent needs structured state.

When cflow discover --json returns status: "blocked", agents must not immediately retry blocked.failingQuery. Report blocked.kind and blocked.scope, inspect search quota with the recommended command if useful, then wait or narrow discovery with --lang, --topic, or --type.

After cflow pr --draft --json, agents should run cflow next --json and stop when the state is ready_for_human_review.

Public Action Rule

Agents must ask for explicit human approval before pushing branches, opening pull requests, posting comments, or making other public GitHub changes.