SuperAI

SuperAI is a private, host-agnostic plugin repository for agentic coding CLIs.

It provides reusable skill packs, role guides, command workflows, mode guidance, and reference assets that can be adapted to different hosts without forking core behavior.

Quick Start

1) Detect supported host CLIs

npx superai-plugin detect

Supported in v1:

• Codex
• Claude
• GitHub Copilot CLI
• Gemini CLI
• OpenCode

2) Install plugin (interactive host selection)

npx superai-plugin install

The installer:

• Detects installed CLIs
• Lets you mark which hosts to apply
• Installs SuperAI skills and MCP entries per selected host
• Backs up previous state to ~/.superai/installer/backups

3) Uninstall plugin (per host)

npx superai-plugin uninstall

Restore the latest backup for one host:

npx superai-plugin restore --host codex

4) Non-interactive examples

npx superai-plugin install --hosts codex,gemini-cli --yes

npx superai-plugin uninstall --hosts codex --yes

Legacy script-based install (advanced)

.\scripts\install_superai_skills.ps1 -TargetDir "$HOME\.codex\skills" -Force

SUPERAI_TARGET_DIR="$HOME/.codex/skills" ./scripts/install_superai_skills.sh --force

3) Configure MCP servers for Codex (PowerShell, optional)

.\scripts\setup_superai_mcp.ps1

Optional servers:

.\scripts\setup_superai_mcp.ps1 -IncludeOptional

4) Configure MCP servers for Codex (Bash, optional)

./scripts/setup_superai_mcp.sh

Optional servers:

./scripts/setup_superai_mcp.sh --include-optional

Override output path when needed:

$env:SUPERAI_CONFIG_PATH="$HOME\\.codex\\config.toml"; .\scripts\setup_superai_mcp.ps1

SUPERAI_CONFIG_PATH="$HOME/.codex/config.toml" ./scripts/setup_superai_mcp.sh

Repository Layout

• skills/ - Skill packs (SKILL.md, references, optional agents metadata).
• scripts/ - Installers, validation, and utility workflows.
• compatibility/ - Host support matrix and compatibility policy.

Compatibility

Official matrix is in compatibility/cli-matrix.yaml. Host install/runtime mapping is in compatibility/host-command-map.yaml. Smoke-test gate is in compatibility/smoke-test-checklist.md.

Initial production targets:

• Codex
• Claude
• Aider
• GitHub Copilot CLI
• Gemini CLI
• OpenCode

Core skills remain host-agnostic. Host-specific behavior is allowed only when feature parity requires explicit adapters.

Use host adapter runbooks for native MCP setup:

• docs/adapters/codex.md
• docs/adapters/claude.md
• docs/adapters/aider.md
• docs/adapters/copilot-cli.md
• docs/adapters/gemini-cli.md
• docs/adapters/opencode.md

Skill Contract

Every SKILL.md must include YAML frontmatter with:

• name
• description
• category
• compatibility
• stability

Required validation:

.\scripts\validate_skills.ps1

./scripts/validate_skills.sh

python ./scripts/validate_command_refs.py

Reference-Heavy Navigation

• skills/sa-repo-core/ - Repo policy references, architecture index, and contributor docs.
• skills/sa-src-core/ - Source-level reference mirror and command/mode/agent definitions.
• skills/sa-docs-reference/ - Troubleshooting, feature references, and examples.
• skills/sa-docs-user-guide/ - User-facing operational guidance.
• skills/sa-docs-development/ - Build, roadmap, and architecture evolution docs.

Skill Menu Shortcuts

• skills/sa-docs/ - Menu for all sa-docs-* skills.
• skills/sa-commands/ - Menu for all sa-command-* skills.
• skills/sa-agents/ - Menu for all sa-agent-* skills.
• skills/sa-modes/ - Menu for all sa-mode-* skills.

Production Usage Notes

• This repository is private and intended for controlled deployment.
• Validate all changes before merge.
• Prefer host-agnostic updates; isolate host-specific behavior to adapter-scoped content.

Contributing

See CONTRIBUTING.md for workflow, quality gates, and review policy. Release gate checklist is in docs/release-checklist.md.

Security

See SECURITY.md for reporting and hardening expectations.

Changelog

See CHANGELOG.md for release history.