groundwork

Groundwork

A comprehensive skills library for Claude Code, consolidating proven techniques for planning, design, TDD, debugging, collaboration, and problem-solving.

Installation

Via Marketplace

First, add the Groundwork marketplace:

claude plugin marketplace add https://github.com/etr/groundwork-marketplace

Then install the plugin:

claude plugin install groundwork

Update via Marketplace

claude plugin marketplace update groundwork-marketplace

claude plugin update groundwork

Manual Installation

cd ~/.claude/plugins
git clone https://github.com/etr/groundwork.git

Or use the installer provided with the codebase.

Other Platforms (Experimental)

Warning: Installation on platforms other than Claude Code is experimental. Skills and agents are automatically transformed to work without Claude Code's plugin system, but some features (hooks, slash commands, skill chaining) may not work identically. Use at your own risk.

Groundwork skills and agents can be installed into other AI coding tools using the included installer script. The installer transforms skill content to remove Claude Code-specific constructs and adapts the format for each target.

Supported Targets

Target	Flag	Description
Codex CLI	--codex	Agents are installed as native custom-agent TOML files with Codex model and reasoning settings
OpenCode	--opencode	Agents are installed as standalone agent files
Kiro	--kiro	Agents use JSON config + prompt file pairs
Pi	--pi	Agents install as review-prefixed skills, plus a pre-built TypeScript extension (pi-extension/)
Claude Code	--claude-code	Recommends the marketplace install (no transformation needed)

Codex Agent Conversion

Codex agents are written to .codex/agents/*.toml for project installs (or ~/.codex/agents/*.toml globally). Claude model metadata maps as follows:

Claude agent model	Codex model override
sonnet	gpt-5.6-terra
opus[1m]	gpt-5.6-sol
inherit or absent	No override; inherit the active Codex model

Supported effort values (low, medium, high, and max) are preserved as model_reasoning_effort; an absent effort is omitted. Unsupported model or effort values stop the install with an explicit error so a silent fallback cannot select an unintended model.

When installing Codex agents, the installer also removes the exact legacy .codex/skills/review-<bundled-agent>/SKILL.md file for each bundled Groundwork agent. It does not use a wildcard: unrelated review-* skills and any sidecar files are preserved, and an empty legacy directory is removed.

Installation

Clone the repository and run the installer:

git clone https://github.com/etr/groundwork.git
cd groundwork

Install globally (available in all projects):

./install-skills.sh --codex --global

Install for the current project only:

./install-skills.sh --opencode --project

You can install to multiple targets at once:

./install-skills.sh --codex --opencode --kiro --global

Installer Options

Option	Description
--global	Install to user-level config directory
--project	Install to current project directory
--force	Overwrite existing files
--dry-run	Preview actions without making changes
--skills-only	Install only skills (skip agents)
--source DIR	Groundwork source directory (default: auto-detect)

What Gets Installed

• Skills — Workflow definitions (planning, TDD, debugging, etc.) are installed with a groundwork- prefix. On OpenCode, skill dependencies are automatically inlined as appendix sections.
• Agents — Verification and review agents (code quality, security, architecture alignment, etc.) are installed in each target's native agent format.
• Hooks — Not installed automatically. Event-driven automations (session start, pre-compact, commit alignment) require manual setup for each tool.
• Slash invocation — Not applicable on other tools. Groundwork has no separate commands layer; other tools discover skills directly by name rather than through Claude Code slash commands.

Limitations

• Hooks (SessionStart, PreCompact, PostToolUse) are not portable and must be configured manually for each tool
• On OpenCode, complex multi-skill workflows may lose interactivity since skill dependencies are inlined as static appendix sections rather than invoked at runtime
• Update checking is not available outside Claude Code

Verify Installation

Restart Claude Code or start a new session. You should see:

• Start typing /groundwork:. It should show groundwork skills available