Skip to content

Keeping the agent skill in sync with the CLI

Source of truth

crm/skills/ is the canonical agent skill — a thin SKILL.md router plus reference/*.md files loaded on demand. The package ships the whole tree (package_data in setup.py; bundled in crm.spec) and crm skill install copies it into an agent's skill directory:

Target Destination
claude ~/.claude/skills/crm/
copilot ~/.copilot/skills/crm/
cursor ~/.cursor/rules/crm/ 
crm skill install --target claude --force

Two rules that keep the skill healthy

  1. Self-contained. The skill ships to users who have only the skill, not this repo. No shipped skill file may link to a repo-only path (docs/**, CONTEXT.md, ../) or assume any repo file is present. Inline what the agent needs (labels, templates, tables). The only assumed externals are the installed crm binary and, for the feedback flow, the gh CLI.
  2. Never restate flags. crm describe [group] and crm <group> --help emit every command, option, choice, default, and envvar straight from the live Click tree — they cannot drift. The skill states only what they cannot: workflows, gotchas, and the JSON contract. Maintenance test: if a line could be regenerated by crm describe, delete it.

crm/tests/test_skill_bundle.py enforces both rules plus a router line cap.

When the CLI changes

Use the writing-great-skills skill (.claude/skills/writing-great-skills/) as the authority for skill structure, progressive disclosure, and description-writing whenever you edit the skill — the two crm-specific rules above override it on conflict.

After adding or changing a command, update the relevant crm/skills/reference/*.md (workflows and gotchas — not flag definitions already in --help; flags appear in examples) and the SKILL.md map if a new group appeared, then reinstall with --force. To detect drift against an install:

diff -r crm/skills ~/.claude/skills/crm

The bug loop used to build CRMWorx

While building the walkthrough, defects were handled with a hybrid policy:

  • Trivial / single-function: write a failing test in crm/tests/, fix in crm/, re-run, continue — the fix lands in the same session.
  • Larger: file a triaged GitHub issue with a minimal repro, work around, continue.

Issues filed during the run are tracked in GitHub Issues.