stefano
251148c3ff
## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
189 lines
9.8 KiB
Markdown
189 lines
9.8 KiB
Markdown
# 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/ — user-facing docs (see docs/README.md)
|
|
├── skills/
|
|
│ ├── atlassian/
|
|
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/ shared/
|
|
│ ├── create-plan/
|
|
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
|
│ ├── do-task/
|
|
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
|
│ ├── implement-plan/
|
|
│ │ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
|
│ ├── reviewer-runtime/
|
|
│ │ ├── pi/ — Pi-specific run-review.sh + notify-telegram.sh
|
|
│ │ └── tests/ — reviewer-runtime smoke tests
|
|
│ └── web-automation/
|
|
│ ├── codex/ claude-code/ cursor/ opencode/ pi/
|
|
├── pi-package/
|
|
│ └── skills/ — Pi-facing mirror synced by sync:pi
|
|
├── scripts/
|
|
│ ├── lib/ — shared Node helpers + portable.sh
|
|
│ └── tests/ — Node.js unit tests
|
|
├── package.json
|
|
└── pnpm-workspace.yaml
|
|
```
|
|
|
|
## Where to Read Next
|
|
|
|
See **[docs/README.md](docs/README.md)** for the full documentation index with
|
|
ordered reading flow, one-line summaries for every doc, and links to per-agent
|
|
install guides, skill docs, Pi docs, Telegram setup, and development notes.
|
|
|
|
## 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 | cursor | 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`
|
|
- Shared workflow setup: `docs/TELEGRAM-NOTIFICATIONS.md`, `docs/PI-SUPERPOWERS.md`, `docs/PI-COMMON-REVIEWER.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/generate-skills.mjs`
|
|
- `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
|
|
pnpm run sync:pi
|
|
npm run verify:pi
|
|
npm run verify:reviewers
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
Additional pi-specific guidance lives in [docs/PI.md](docs/PI.md).
|
|
|
|
For development prerequisites, quality tooling, and the `pnpm run check`
|
|
contract, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
|
|
|
|
## Contributing / Development
|
|
|
|
See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** for the full development guide.
|
|
|
|
Quick reference — the single quality gate every contributor must pass:
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm run check # lint · typecheck · test · verify:pi · verify:reviewers · verify:docs · verify:generated
|
|
```
|
|
|
|
Prerequisites: Node.js 20+, pnpm 10+, `shellcheck` (brew / apt), `ripgrep` (brew / apt).
|
|
|
|
CI runs the same `pnpm run check` command on both `ubuntu-latest` and `macos-latest`
|
|
(see `.github/workflows/check.yml`). External link checking runs separately on a
|
|
weekly schedule (`.github/workflows/check-online.yml`).
|