Skill Management

Skill Sources (canonical)

CLI Tool Skill Directories

Deduplication

Four sync targets cover all five CLIs:

1. ~/.claude/skills/ — Claude Code
2. ~/.agents/skills/ — Codex + Gemini (shared open standard)
3. ~/.gemini/antigravity-cli/skills/ — Antigravity (agy)
4. $CHARLIEBOT_HOME/.claude/skills/ — Claude Code cwd-ancestor root. Claude Code collects .claude/skills/ from every ancestor of its cwd up to $HOME, independent of the logged-in account, and a master session's cwd sits under $CHARLIEBOT_HOME/, so this one root reaches every Claude account's masters; the per-account config dirs get no target. The same file visible through two roots (this one and ~/.claude/skills/) loads once.

OpenCode and charlie-code need no target: both auto-scan ~/.claude/skills/ and ~/.agents/skills/, already populated above.

Every real sync ends with a Claude discovery check (skipped under -n and when claude is not on PATH): sync-skills.sh starts claude once with an empty CLAUDE_CONFIG_DIR from the $CHARLIEBOT_HOME/sessions cwd — not logged in, zero API calls — and reads K, the project count on the last Loaded N unique skills (... project: K ...) line of its debug log, against N, the symlink count in target 4. It prints Claude discovery: K/N and exits 1 when the line is missing or K differs from N.

Sync Rules

• Each skill entry in target dirs is a symlink pointing to the canonical source
• Never overwrite non-symlink entries or dotfiles (e.g. Codex .system/)
• Remove stale symlinks whose targets no longer exist
• Sync script: <charlie-bot-repo>/scripts/sync-skills.sh
• Workers see skills through the backend CLI's skill dir — not directly from $CHARLIEBOT_HOME/skills/.

Host-Specific Content Boundary

Repo-level shared files (<charlie-bot-repo>/skills/**, <charlie-bot-repo>/prompts/**) MUST NOT contain host-specific info — hostnames, local paths, GPU specs, per-host ports/IPs. Anything host-specific belongs in the memory store's host topic ($CHARLIEBOT_HOME/memory/entries/host/) or $CHARLIEBOT_HOME/skills/<name>/. Rules like "feature X is local-host only" must be flagged in the repo-level skill so that workers running anywhere see them.

Repo-level skills must also stay free of session-specific debug artifacts: dated transcripts (observed in D4, 2026-05-04 run), internal task IDs, specific bug strings (bytes-vs-str + train_ranges API mismatches), or any phrasing that reads like a LESSONS.md entry. Workers loading shared skills cannot see $CHARLIEBOT_HOME/LESSONS.md and have no context for those references. Keep shared skills as static principles; only promote a finding into a shared skill once the debug is closed and the lesson rewrites cleanly as a generic rule.

A local pre-commit hook enforces this boundary. One-time setup per clone:

git config --local core.hooksPath tools/git-hooks

Additional host-specific blocklist patterns (real names, internal project names, tenant identifiers, etc.) live at $CHARLIEBOT_HOME/skills_leak_patterns.local.txt — one regex per line, NEVER committed to this repo. The host patterns scan every tracked file, including decompressed gzip files. The hooks scan staged files, commit messages, and commit identities.

Person-Identifying Session Content Boundary

Repo-level shared files also carry no material that identifies a real person when read together with the repository's public authorship: names, orders, preferences, schedules, or other session-derived personal data. Examples in skills and docs are synthetic end to end, covering people, items, and quantities alike, even when a real session supplies the template. The authoring-time test: a reader who knows this repository's owner learns nothing about any real person from the content. tools/check-skills-host-leak.sh scans for host identifiers only, so this boundary rides on the author's judgment; a skill drafted from a live session applies the test to every example before it lands.

File Name Convention

All CLIs require SKILL.md (exact name, case-sensitive) as the entry point file.

Updating Existing Skills

When new lessons surface and a skill needs an update, follow these rules:

• Reorganize, don't append. If related content already lives in the skill, edit the existing section in place rather than tacking on a new paragraph. Skills must stay concise so they remain scannable; growing them by accretion (one new bullet per session) defeats the purpose. Re-read the whole skill first, then propose the smallest diff that captures the new lesson.
• Ask before modifying any local skill. Surface the intended edit to the user before writing it — never silently mutate a skill file, even when "just adding a clarifying line".
• Always present the change as a file diff. Show the actual before/after (or Edit patch) so the user can see surrounding context and judge whether the edit fits. Don't summarize the change as "I'd add a note about X" — the user needs to see the literal lines being added/changed/removed to approve.