Plan: Migrate ai-agents-oss-helper commands to a single background skill

parallel-rolling-bird.md

Plan: Migrate commands to a single background skill

Context

The project currently ships 25 markdown files in commands/ that are installed as individual /oss-* commands for various AI agents. Claude Code has evolved: commands are now merged into skills, and skills are recommended going forward. Skills support auto-invocation, supporting files, and frontmatter control.

The goal is to replace the 25 individual commands with one background skill (user-invocable: false) that Claude auto-loads when the user's request is relevant (e.g., "review PR #42", "fix issue CAMEL-123"). No explicit / invocation needed.

Source structure change

Before:

commands/
├── .oss-init.md
├── oss-fix-issue.md
├── oss-review-pr.md
├── oss-quick-fix.md
└── ... (25 files)

After:

skills/oss-helper/
├── SKILL.md                          # Main skill: description, init logic, capability catalog
├── fix-issue.md                      # Guidelines for fixing issues
├── review-pr.md                      # Guidelines for reviewing PRs
├── quick-fix.md                      # Guidelines for quick fixes
├── analyze-issue.md
├── find-task.md
├── create-issue.md
├── fix-sonarcloud.md
├── fix-github-alert.md
├── add-project.md
├── update-knowledge.md
├── fix-ci-errors.md
├── fix-backlog-task.md
├── pr-status.md
├── list-pr-status.md
├── list-prs.md
├── list-issues.md
├── backport-pr.md
├── address-review.md
├── merge-pr.md
├── create-security-advisory.md
├── triage-security-report.md
├── draft-cve.md
├── analyze-third-party-cve.md
└── install-info.md

Files drop the oss- prefix (redundant inside oss-helper/).

Content changes per file

Each guideline file:

• Remove the # Title heading (name is clear from filename and SKILL.md catalog)
• Remove ## Usage and ## Arguments sections (no explicit invocation)
• Remove the "MANDATORY: First, read and process the .oss-init.md file" step from each file (init logic moves to SKILL.md)
• Keep all ## Instructions content — the step-by-step guidelines are the core value

SKILL.md design

---
name: oss-helper
description: >
  Guidelines for contributing to open source projects. Covers fixing issues,
  reviewing PRs, creating issues, finding tasks, backporting, CI fixes,
  SonarCloud fixes, security triage, and more. Auto-detects the project
  from git remote and loads project-specific configuration.
user-invocable: false
---

The body of SKILL.md contains:

1. Project initialization logic (current .oss-init.md content — project detection, rule loading, version check)
2. Capability catalog — a table mapping user intents to supporting files, so Claude knows which file to read:

When the user wants to...	Read
Fix an issue (GitHub or Jira)	fix-issue.md
Review a pull request	review-pr.md
Apply a quick fix	quick-fix.md
...	...

3. Instruction: Always run project initialization first, then read the appropriate guideline file.

install.sh changes

Claude

• Before: Copy files to ~/.claude/commands/
• After: Copy skills/oss-helper/ directory to ~/.claude/skills/oss-helper/
• Add current command filenames to OLD_COMMAND_FILES for cleanup

Bob

• Same as Claude but under ~/.bob/skills/oss-helper/
• Add cleanup of old ~/.bob/commands/oss-*.md files

Gemini

• Gemini has no skill auto-loading. Keep installing individual TOML commands.
• Read each guideline file from skills/oss-helper/, prepend init preamble, convert to TOML.
• The TOML commands still tell Gemini to read rule files from ~/.gemini/rules/.
• Add cleanup of old command files.

OpenCode

• Same approach as Gemini: read from skill source, convert to individual commands with frontmatter.
• Add cleanup of old command files.

Codex

• Before: Individual skills in ~/.agents/skills/<name>/SKILL.md
• After: Single skill directory at ~/.agents/skills/oss-helper/SKILL.md + supporting files
• Clean up old individual skill directories.

Cleanup arrays

Add all 25 current oss-*.md filenames to OLD_COMMAND_FILES so existing installations get cleaned up.

README.md changes

• Update "Project Structure" section to show skills/oss-helper/ layout
• Update installation notes to explain the skill-based approach
• Keep the capability table but reframe from "commands" to "capabilities"
• Update agent-specific sections (Codex notes, Gemini notes, OpenCode notes)
• Remove /oss-* invocation syntax from examples; show natural language instead

Implementation order

1. Create skills/oss-helper/SKILL.md with frontmatter, init logic, and catalog
2. Move each commands/oss-*.md to skills/oss-helper/<name>.md with content cleanup
3. Remove commands/ directory
4. Update install.sh: new source paths, Claude/Bob skill install, cleanup arrays
5. Update README.md

Verification

1. Run ./install.sh claude and verify ~/.claude/skills/oss-helper/ is created with all files
2. Run ./install.sh gemini and verify TOML commands are still generated correctly
3. Run ./install.sh codex and verify single skill directory replaces old individual skills
4. Check that old command files are cleaned up from ~/.claude/commands/
5. Verify the skill appears in Claude Code's skill list (not user-invocable, so it should NOT show in / menu but should auto-load when relevant)