Install DB9 Skills

db9 onboard installs or updates the DB9 skill file into supported coding agents. The skill teaches agents how to use the db9 CLI and SQL for database management, queries, file operations, branching, and scheduling.

How It Works

1. The CLI detects which agents are installed on your system
2. It downloads the latest skill file from https://db9.ai/skill.md (or uses an embedded fallback if the download fails)
3. It compares versions and writes SKILL.md to each agent’s skills directory
4. The agent reads the skill file as context on future sessions

The onboard command never sends tokens or credentials. It only writes a Markdown file to your local filesystem.

Quick Start

Terminal

# Interactive — auto-detects installed agents and prompts
db9 onboard

# Non-interactive, install for all detected agents
db9 onboard --yes --all

# Install for specific agents
db9 onboard --yes --agent claude --agent codex

Supported Agents

Agent	--agent value	User scope path	Project scope path	Supports --scope project?
Claude Code	claude	~/.claude/skills/db9/SKILL.md	./.claude/skills/db9/SKILL.md	Yes
OpenAI Codex	codex	~/.codex/skills/db9/SKILL.md	—	No (user only)
OpenCode	opencode	~/.config/opencode/skills/db9/SKILL.md	./.opencode/skills/db9/SKILL.md	Yes
Generic agents	agents	~/.agents/skills/db9/SKILL.md	./.agents/skills/db9/SKILL.md	Yes

• Codex respects the CODEX_HOME environment variable. If set, the skill installs to $CODEX_HOME/skills/db9/SKILL.md instead of ~/.codex/....
• Generic agents (--agent agents) targets a shared ~/.agents/ directory for agent frameworks that follow this convention.

Scope

The --scope flag controls where the skill file is written:

Scope	Behavior
--scope user (default)	Installs to the user’s home directory. Skill is available in all projects.
--scope project	Installs relative to the current working directory. Skill is scoped to this project.
--scope both	Installs to both locations (when supported by the agent).

Terminal

# User scope (default)
db9 onboard --yes --agent claude

# Project scope
db9 onboard --yes --agent claude --scope project

# Both scopes
db9 onboard --yes --agent claude --scope both

Codex limitation: OpenAI Codex currently supports only --scope user. Requesting --scope project --agent codex explicitly will produce an error. When using --all --scope project, Codex is automatically skipped with a warning.

Auto-Detection

When you run db9 onboard without --agent or --all, the CLI detects which agents are installed:

Agent	Detection method
Claude Code	claude binary on PATH or ~/.claude/ directory exists
OpenAI Codex	codex binary on PATH, $CODEX_HOME exists, or ~/.codex/ exists
OpenCode	opencode binary on PATH or ~/.config/opencode/ exists
Generic agents	~/.agents/ or ./.agents/ directory exists

If no agents are detected, the CLI prints a tip suggesting explicit --agent flags.

Safety and Introspection

Dry run

Preview all actions without writing anything:

Terminal

db9 onboard --dry-run

Output shows each target with its planned action (install, update, or skip) and the reason.

Print locations

Show resolved file paths without downloading or writing:

Terminal

db9 onboard --print-locations
db9 onboard --print-locations --agent claude --scope both

Version comparison

The skill file uses semantic versioning in its YAML frontmatter (version: 1.0.0). On update:

• If the local version matches the remote, the file is skipped (up-to-date)
• If the local version is older, the file is updated
• If the local version is newer (e.g., you customized it), the update is skipped — use --force to override

Backup

When updating an existing skill file, the CLI creates a timestamped backup (e.g., SKILL.md.bak.1710000000000) before overwriting.

Atomic writes

File writes use a temporary file and atomic rename to prevent partial installs.

Update and Force

Terminal

# Update to the latest skill version
db9 onboard --yes --all

# Force overwrite even if local version is newer
db9 onboard --yes --agent claude --force

Custom Skill Source

Point to a custom skill file instead of the default https://db9.ai/skill.md:

Terminal

# From a URL
db9 onboard --agent claude --skill-url https://example.com/custom-skill.md

# From a local file
db9 onboard --agent claude --skill-path ./my-custom-skill.md

If the remote URL download fails and the default URL was used, the CLI falls back to an embedded copy of the skill bundled into the binary.

All Flags Reference

Flag	Description
--agent <AGENT>	Agent to install for (repeatable). Values: codex, claude, opencode, agents.
--all	Install for all supported agents.
--scope <SCOPE>	Install scope: user (default), project, or both.
--yes / -y	Skip prompts and choose safe defaults.
--dry-run	Print intended actions and make zero filesystem changes.
--force	Overwrite existing skill even when local version is newer.
--print-locations	Print resolved target locations without writing.
--skill-url <URL>	Skill source URL (default: https://db9.ai/skill.md).
--skill-path <PATH>	Install from a local skill file instead of downloading.

Current Limitations

• Codex is user-scope only — project-scope support may be added in a future Codex release.
• No automatic updates — the skill file includes an instruction for agents to re-read from the URL periodically, but db9 onboard itself must be re-run to update the on-disk file.
• Agent-specific skill directories are a convention — if an agent framework changes its skills directory path, db9 onboard needs a CLI update to match.

Next Pages

• DB9 with Claude Code — Claude Code-specific setup and example prompts
• DB9 with OpenAI Codex — Codex-specific setup and scope constraints
• Agent Workflows Overview — how DB9 fits into agent pipelines
• CLI Reference — complete command reference including db9 onboard