Installation

Install only generated artifacts under dist/. Never copy src/, source registries, reports, or personal content into an agent configuration. Run all commands from the repository root with Python 3.11 or newer after python3 -m pip install ..

For the shortest build/install/doctor path, start with Quickstart.

Build

Build the one Runtime:

python3 scripts/build.py

The build emits exactly 26 top-level Skills: 1 Control and 25 Professional. Foundation and Domain Skills remain in the complete source inventory and are compiled only as Professional-owned JIT Layer 3 guidance. Runtime build owns composition, temporary completeness validation, supported-host Agent Profile output, and manifest fields. Every installer validates the built manifest before changing its target.

The internal directory and manifest identity remains recommended for compatibility. It is fixed and is not a CLI choice.

Host, Scope, And Default Targets

Codex, Claude, and Copilot install the four static Agent Profiles. Cline installs Skills without native Agent Profile files. OpenAI API produces zip files only and has no runtime target.

For project, --target means the project root and is required. For user or Codex admin, --target means an explicit Skill directory, not a project root. An explicit user/admin Skill target does not relocate the host's default Agent Profile target. Omit --target to use the defaults above.

Codex admin writes below /etc/codex; preview it first and use only an approved privilege boundary. Claude, Copilot, and Cline reject admin scope.

Install

Replace /absolute/path/to/project with an existing project root. Always preview the same command first:

python3 installers/install.py \
  --agent codex --scope project --target /absolute/path/to/project \
  --dry-run
python3 installers/install.py \
  --agent codex --scope project --target /absolute/path/to/project

User installation needs no target when the default is correct:

python3 installers/install.py --agent claude --scope user --dry-run
python3 installers/install.py --agent claude --scope user

The installer rejects unmanaged artifacts whose names collide with incoming rd-skills artifacts. Inspect every reported path before considering --force. Use --force only when replacement of those exact unmanaged same-name artifacts is intended and separately recoverable. It does not bypass source validation, path containment, unsupported scopes, or unsafe names.

Optional install --backup copies only incoming or previously managed rd-skills paths, the install manifest, and bounded known legacy paths that already exist. It writes below the Skill target's .changeforge-backups/ directory and is not a full Host-configuration snapshot.

Doctor

python3 installers/doctor.py --agent codex --scope user

Doctor checks the manifest, 26 top-level Skill roots, current build/core/source bindings, legacy residue, and the host-specific Agent Profile contract. Codex, Claude, and Copilot must have the exact four-role file set; Cline correctly has none. An exact historical 27-Skill recommended, 40-Skill full, or 190-Skill dev manifest is reported as migration-required before current build-digest checks. Doctor is artifact evidence, not proof of real-Host startup.

Upgrade And Legacy Runtime Migration

Build first, then preview and run upgrade. Do not uninstall an existing full or dev installation first:

python3 scripts/build.py
python3 installers/upgrade.py --agent codex --scope user --dry-run
python3 installers/upgrade.py --agent codex --scope user
python3 installers/doctor.py --agent codex --scope user

Upgrade requires an existing rd-skills manifest. It accepts the exact current 26-Skill recommended inventory and the closed historical 27/40/190 recommended/full/dev generation, validates ownership, and migrates each historical inventory to the fixed Runtime manifest. The historical bridge is embedded installation metadata with fixed layer fingerprints; it does not read Git history or infer ownership from arbitrary current Registry contents. It removes the retired managed routing-quality-review directory, managed top-level Domain Skills from full, and managed top-level Foundation Skills from dev. It does not require an intermediate uninstall.

All five inventory fields must match one supported generation exactly. Extra, missing, replacement, duplicate, unsafe, or current/historical hybrid names fail before backup or target mutation, and --force does not bypass this ownership check.

Before any live cleanup or replacement, upgrade must create a complete backup of the currently managed Skill directories, managed Agent Profile files, manifest, and bounded known legacy paths. If that backup cannot be completed, upgrade stops before mutation. The resulting path is printed and recorded in the new manifest.

Ownership is directory-granular for a managed top-level Skill. Unmanaged top-level files and directories remain in place. A user file mixed inside a managed Skill directory is included in the backup, but the managed directory is then replaced as a unit; restore that mixed-in file selectively from the backup after verifying it belongs there. Upgrade never deletes an unrelated top-level user Skill merely because a legacy Runtime is being migrated.

Upgrade is not crash-atomic across legacy cleanup, Skill replacement, Agent Profile replacement, and final manifest write. If it is interrupted after the backup, stop further writes, inspect the newest upgrade-* backup, compare its skills/, profiles/, and optional legacy/ contents with the target, and restore only verified files through the normal filesystem or configuration management process.

rd-skills has no automatic restore CLI. Do not copy the backup root wholesale over unrelated Host content. If no usable backup exists, stop rather than guessing ownership.

Uninstall

python3 installers/uninstall.py --agent codex --scope user --dry-run
python3 installers/uninstall.py --agent codex --scope user

Uninstall accepts current and exact supported historical manifests and removes only the classified generation's declared managed inventory plus bounded known legacy artifacts. It does not remove unrelated user content or restore a backup automatically.

OpenAI API Zip Output

Generate and validate the fixed Runtime zip set:

python3 scripts/build.py
python3 scripts/package.py
python3 installers/install.py --agent openai-api

Build and package write 26 zip files under the compatibility path dist/openai-api/zips/recommended/. Each zip is named for one top-level Control or Professional Skill and contains exactly one matching folder with a root SKILL.md. Foundation and Domain Skills never receive top-level zips. The installer command validates the local bundles; it does not upload or install them. These files are not evidence of official marketplace publication.

Builds, zip validation, quickstart, installer, and doctor results prove only the declared local artifact contracts. They do not prove real-host Profile startup, wall-clock performance, production accuracy, provider behavior, or the installed user experience.

Troubleshooting And Recovery

For migration-specific behavior and rollback, see Migration to the hookless architecture. For task requests after a healthy install, continue to Usage.