CCL Skills

Reusable workflows that help coding agents plan, build, test, review, and release software.

CCL Skills works with Claude Code, Codex, OpenCode, and other tools that support Agent Skills.

flowchart LR
    A[Your task] --> B[Choose the right skill]
    B --> C[Follow its steps]
    C --> D[Use its references and scripts]
    D --> E[Run tests and review]
    E --> F[Deliver the result]
    F -. Keep what works .-> B

Quick start

Install the unified package with Node.js 20 or later:

npm install --global @ccoalm/ccl-skills
ccl-skills install

The npm tarball includes the skills, agent context, plugin manifests, and runtime hooks. Claude Code and Codex consume the plugin hooks directly. OpenCode installs a native plugin plus the same bundled hook runtime, including edit isolation for edit, write, and apply_patch. Installation does not need a Git checkout.

If npm returns E404 before the initial registry release, install from source:

git clone https://github.com/ccoalm/ccl-skills.git
cd ccl-skills
make install

Both install paths configure every CLI they detect — Claude Code, Codex, and OpenCode. Restart the CLI afterwards so it reloads the skills.

Confirm the install landed:

claude plugin list            # expect ccl-skills@ccl-skills
codex plugin list             # expect ccl-skills
ls ~/.config/opencode/skills  # expect the skill directories
test -f ~/.config/opencode/ccl-skills/runtime/hooks/hooks.json

To pin one OpenCode project to this checkout instead of the global install:

bash scripts/install-opencode.sh --project

Run make help for every install, update, and evaluation target. The unified npm package lives in packages/ccl-skills-npm and requires Node.js 20 or later.

Install and update

npm installs use one command for all detected hosts:

ccl-skills update       # preview; no network or global mutation
ccl-skills update --yes # upgrade the package and refresh host assets

By default update --yes upgrades the global npm package to @latest first. Set CCL_SKILLS_SKIP_SELF_UPDATE=1 for an assets-only refresh; --allow-downgrade always uses the currently invoked package instead of installing @latest.

Git-checkout installs use make update.

The host-specific behavior is:

For npm installs, Claude and Codex register package-owned local marketplaces and consume their plugin hooks. OpenCode installs its skills, native plugin, and hook runtime into host-visible shared paths after collision checks. npm uninstall retains those shared files and reports them for manual cleanup.

Claude keeps one cache directory per installed version and they accumulate. make prune-cache removes the stale ones and keeps the active version; it refuses to delete anything when it cannot determine which version is active.

Install the gates into your own repository

The repository checks are also distributable. This adds the agent-contract, owner-dispatch, and control-plane gates to a product repository:

make install-gates TARGET=/path/to/repo

The install is additive and starts warn-only because the installer cannot infer a target repository's owner mappings, baseline cleanliness, false-positive history, or risk tolerance. Enforcement is a deliberate repository decision: verify the specific gate is deterministic and ready, then set enabled: true, pass --enforce in CI, and remove allow_failure. This is an installation default, not a universal warn-to-block maturity sequence for every signal.

Use a skill

Ask for a skill by name:

Use product-rd-workflow to plan and deliver this feature.
Use defect-diagnosis to find the cause of this failure.
Use testing-strategy to add regression coverage.

The coding agent can also choose a skill from the task. It reads skills/<name>/SKILL.md first, then opens the references and scripts needed for that work.

Find the right skill

docs/SKILLS.md is the single authoritative catalog. It lists every skill in skills/, grouped by delivery stage, and gives each one two lines: when to use it, and when to use something else instead. Start there — this README deliberately keeps no second list of its own.

Supported tools

Use npx to run the package without installing it globally. If the registry still returns E404, use the checkout alternative.

Repository layout

skills/           Skills, references, and their scripts
agent-context/    Text injected into agent sessions; one file per injecting hook
docs/             Guides for users and contributors
hooks/            Canonical runtime checks consumed by Claude Code, Codex, and the OpenCode adapter
scripts/          Installers, gate installers, and repository checks
packages/         Unified npm package and the standalone OpenCode plugin source
eval/             Skill evaluation cases
specs/            Design notes for in-flight repository changes
.claude-plugin/   Claude Code marketplace and plugin manifests
.codex-plugin/    Codex plugin manifest
.agents/          Codex marketplace manifest
.github/          CI workflow
.githooks/        Opt-in local git hooks; enable with `git config core.hooksPath .githooks`
opencode.json     OpenCode config for using the skills from inside this checkout
AGENTS.md         Rules for coding agents working in this repository
.worktree-only    Repository-root marker: edits here must go through a worktree

docs/ARCHITECTURE.md carries the full table, including what each manifest is for and which hook runs on which event.

Contributing

Read the contribution guide before making a change. It covers worktree setup, repository rules, review, and required checks.

Verify with make test. It chains the three local lanes CI splits into repository-gates, regression-fast, and the code-review regression and abort-leak jobs. Two CI jobs sit outside it, so a green local run is not a green CI run: regression-heavy, and the check-public-sanitization.py step inside repository-gates. The contribution guide has the per-lane table.

Maintainers should also read the npm release runbook before changing a version or creating a release tag.