Cf Knowledge

CLI Usage: When unsure about a CLI's interface or flags, run it with --help first. Do NOT attempt to discover functionality by reading plugin source code — doing so leads to incorrect execution from assumptions made without context of the holistic flow.

Knowledge Management

Manage the CLEAR knowledge base: search, view, capture, index, link, deprecate, and supersede entries.

Plugin Root Resolution

CLI commands in this skill reference $CLEAR_PLUGIN_ROOT — a .claude/settings.json env var the shell expands. The SessionStart hook persists it, but settings env vars load at session launch, so on a brand-new consumer's first session (before its next restart) the variable is empty and node "$CLEAR_PLUGIN_ROOT/build/..." fails with MODULE_NOT_FOUND.

First-session bootstrap — if $CLEAR_PLUGIN_ROOT is empty, set it inline in the same Bash call as the CLI (each Bash call is a fresh shell, so a separate export would not carry over):

export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"

Prepend it to the CLI in one shell line: export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"; <node "$CLEAR_PLUGIN_ROOT/build/..." command>. ${CLAUDE_PLUGIN_ROOT} resolves in this SKILL.md body to the actually-loaded plugin path; once the consumer restarts, $CLEAR_PLUGIN_ROOT is populated and the assignment is a harmless no-op. Reference files are left unchanged.

When to Use This Skill

Not for: Project status (/cf-status), workpackage ops (/cf-workpackage), debug (/cf-debug).

Command Reference

All CLIs at $CLEAR_PLUGIN_ROOT/build/infrastructure/knowledge/cli/. Run with --clear-dir=./.clear.

Key distinction: link-cli manages workpackage associations only. To add file links (related_files) to a knowledge entry, use the capture-cli update path with the add-related-file option.

Pre-Flight Check

if [ ! -d ".clear" ]; then
  echo "ERROR: CLEAR not initialized. Run /cf-init first." >&2
  exit 1
fi

Subcommand Table

Routing

Follow these steps in order. Track which step you reached — this determines whether confirmation is needed.

Step 1 — Check $ARGUMENTS for an explicit subcommand. Check whether $ARGUMENTS literally starts with one of the subcommand keywords from the table above (e.g., capture, search, deprecate). This is a string match, not intent inference.

• If YES: load references/{subcommand}.md, pass remaining arguments. Done — skip steps 2-4.
• If NO (empty, missing, or does not start with a table keyword): continue to step 2.

Step 2 — Infer intent from the user's natural language message. $ARGUMENTS did not contain an explicit subcommand. Determine which subcommand best matches the user's intent from their message. Use the subcommand table's intent signals, the "When to Use" examples, and the conversation context.

• If you can identify a specific subcommand with reasonable confidence: continue to step 3.
• If the user's message is purely a status or overview inquiry with no action intent (e.g., "show me the knowledge base status"): load references/default.md. Done. Only use this exit if the message contains no entity identifiers (entry ID, WP ID) and expresses no specific action intent.
• If you cannot determine intent with reasonable confidence: go to step 4.

Step 3 — Confirm before write actions (NL-inferred only). You reached this step via intent inference (step 2), not explicit arguments (step 1).

• If the inferred subcommand is a read action ([R] in the table): load the reference file immediately.
• If the inferred subcommand is a write action ([W] in the table): you MUST confirm before proceeding. Ask: "I'll run {subcommand}{details}. Proceed?" where {details} includes the target identifier (e.g., " on TD-015", " superseding TD-002 with PAT-007"). For destructive actions (deprecate, supersede, delete), always include the target ID. Wait for the user's response. Only load the reference file after the user confirms.

Step 4 — Ambiguity fallback. Ask the user: "I matched /cf-knowledge but I'm not sure which action you want. Did you mean: {top 2-3 candidates}?" Do NOT silently fall through to default.

Error Codes

Completion Checklist

• Pre-flight passed
• Correct reference loaded and executed
• Exit code 0, output displayed