ai-coding-skills/README.md

# ai-coding-skills

Cross-agent skill collection for **Codex**, **Claude Code**, **OpenCode**, **Cursor**, and **pi**.

Pi package support is also included for the pi-native variants in this repo.

This repo is organized similarly to `obra/superpowers` and is designed to scale to many skills over time.

## Goals

- Keep skills portable across coding agents.
- Keep each skill self-contained (`skills/<skill-name>/<agent-variant>/SKILL.md` + resources).

## Repository Layout

```text
ai-coding-skills/
├── README.md
├── docs/
│   ├── README.md
│   ├── INSTALLER.md
│   ├── CODEX.md
│   ├── CLAUDE-CODE.md
│   ├── CURSOR.md
│   ├── OPENCODE.md
│   ├── ATLASSIAN.md
│   ├── CREATE-PLAN.md
│   ├── DO-TASK.md
│   ├── IMPLEMENT-PLAN.md
│   ├── PI.md
│   ├── PI-COMMON-REVIEWER.md
│   ├── PI-RESEARCH.md
│   ├── PI-SUPERPOWERS.md
│   ├── TELEGRAM-NOTIFICATIONS.md
│   └── WEB-AUTOMATION.md
├── skills/
│   ├── _template/
│   │   └── SKILL.md
│   ├── atlassian/
│   │   ├── codex/
│   │   ├── claude-code/
│   │   ├── cursor/
│   │   ├── opencode/
│   │   ├── pi/
│   │   └── shared/
│   ├── create-plan/
│   │   ├── codex/
│   │   ├── claude-code/
│   │   ├── opencode/
│   │   ├── cursor/
│   │   └── pi/
│   ├── do-task/
│   │   ├── codex/
│   │   ├── claude-code/
│   │   ├── opencode/
│   │   ├── cursor/
│   │   └── pi/
│   ├── implement-plan/
│   │   ├── codex/
│   │   ├── claude-code/
│   │   ├── opencode/
│   │   ├── cursor/
│   │   └── pi/
│   ├── reviewer-runtime/
│   │   ├── pi/
│   │   └── tests/
│   └── web-automation/
│       ├── codex/
│       ├── claude-code/
│       ├── opencode/
│       └── pi/
├── .codex/
├── .claude-plugin/
├── .opencode/
│   └── plugins/
├── commands/
├── hooks/
└── tests/
```

## Skills

| Skill | Agent Variant | Purpose | Status | Docs |
|---|---|---|---|---|
| atlassian | codex | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
| atlassian | claude-code | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
| atlassian | opencode | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
| atlassian | cursor | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
| atlassian | pi | Portable Jira and Confluence workflows through a shared Cloud-first CLI | Ready | [ATLASSIAN](docs/ATLASSIAN.md) |
| create-plan | codex | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
| create-plan | claude-code | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
| create-plan | opencode | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
| create-plan | cursor | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
| create-plan | pi | Structured planning with milestones, iterative cross-model review, and runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
| do-task | codex | Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit | Ready | [DO-TASK](docs/DO-TASK.md) |
| do-task | claude-code | Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit | Ready | [DO-TASK](docs/DO-TASK.md) |
| do-task | opencode | Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit | Ready | [DO-TASK](docs/DO-TASK.md) |
| do-task | cursor | Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit | Ready | [DO-TASK](docs/DO-TASK.md) |
| do-task | pi | Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit | Ready | [DO-TASK](docs/DO-TASK.md) |
| implement-plan | codex | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
| implement-plan | claude-code | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
| implement-plan | opencode | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
| implement-plan | cursor | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
| implement-plan | pi | Worktree-isolated plan execution with iterative cross-model milestone review | Ready | [IMPLEMENT-PLAN](docs/IMPLEMENT-PLAN.md) |
| web-automation | codex | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
| web-automation | claude-code | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
| web-automation | opencode | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
| web-automation | pi | CloakBrowser-backed browsing, scraping, auth, flow automation, and install validation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |

- Start with the docs index: `docs/README.md`
- Automated install/update/remove wizard: `docs/INSTALLER.md`
- Manual install by client: `docs/CODEX.md`, `docs/CLAUDE-CODE.md`, `docs/CURSOR.md`, `docs/OPENCODE.md`, `docs/PI.md`
- Skill guides: `docs/ATLASSIAN.md`, `docs/CREATE-PLAN.md`, `docs/DO-TASK.md`, `docs/IMPLEMENT-PLAN.md`, `docs/WEB-AUTOMATION.md`

## Compatibility Policy

Each skill should explicitly document agent compatibility and any prerequisites directly in its own `SKILL.md`.

## Skill Manager Wizard

Use the repository skill manager to install, update/reinstall, or remove skills for supported local clients:

```bash
./scripts/manage-skills.sh
# or
node scripts/manage-skills.mjs
```

Useful non-interactive modes and examples:

```bash
# Preview detected clients and planned changes without writing files
node scripts/manage-skills.mjs --dry-run

# Emit a machine-readable operation plan from an answers file
node scripts/manage-skills.mjs --plan-only --answers answers.json

# Install/update a skill for a specific client
node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action install --yes
node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action update --yes

# Remove a skill from a specific client
node scripts/manage-skills.mjs --client claude-code --scope global --skill do-task --action remove --yes

# Install the Pi package globally or project-locally through the manager
node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action install --yes
node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
```

The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report.

`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents.

## Pi Package

The repo root now includes a pi package manifest that ships only the pi-specific surface:

- `pi-package/skills/*/` for the five packaged Pi skills
- `skills/reviewer-runtime/pi/`
- `docs/PI*.md`
- `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
- `scripts/sync-pi-package-skills.sh`
- `scripts/verify-pi-resources.sh`
- `scripts/verify-pi-workflows.sh`
- `scripts/verify-reviewer-support.sh`

Install it from a cloned checkout with the repo-owned one-liner:

```bash
./scripts/install-pi-package.sh --global
```

For a project-local install instead:

```bash
./scripts/install-pi-package.sh --local
```

Prerequisites:

- Node.js 20+
- `pi`
- either `pnpm` on `PATH`, or `corepack` support from the Node install

The repo pins its pnpm version in `package.json` so Corepack-backed installs resolve consistently.

Before publishing or sharing a tarball, run:

```bash
./scripts/sync-pi-package-skills.sh
./scripts/verify-pi-resources.sh
npm pack --dry-run --json
```

Additional pi-specific guidance lives in [docs/PI.md](docs/PI.md).