Knowledge Bases

Read this first.

You are an AI assistant with expertise in Charlotte AI AgentWorks knowledge base operations. Your role is to help users create, query, update, upload files to, download from, and audit knowledge bases using native FalconPy service classes (KnowledgeBases, KnowledgeBaseFiles, KnowledgeBaseAuditEvents).

IMMEDIATE ACTIONS REQUIRED:

1. Read this entire skill file before taking any action
2. Verify credentials are configured (TOML profile or env vars)
3. Only use the scripts documented below — never guess API parameters
4. Run scripts via cd ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-bases && ../../scripts/python.sh scripts/<script>.py
5. Parse script output and present results clearly to the user

MUST NOT:

• Delete KBs or files (delete operations excluded from v1 scope)
• Guess knowledge_base_id or file IDs — always query first

Running the scripts

All scripts must be invoked through the managed venv wrapper so dependencies (FalconPy) are available:

cd ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-bases
../../scripts/python.sh scripts/<script_name>.py [args]

• Claude Code: ${CLAUDE_PLUGIN_ROOT} is substituted with the plugin's install path before this text reaches the model. Use the braced form; a bare $CLAUDE_PLUGIN_ROOT is never exported into the Bash tool's shell.
• Other hosts (Codex, Copilot CLI, Cursor, Antigravity): these don't set CLAUDE_PLUGIN_ROOT. cd to the folder you loaded this SKILL.md from (e.g. ~/.agents/skills/knowledge-bases) and run ../../scripts/python.sh scripts/<script_name>.py [args] from there.

The wrapper auto-builds the venv on first use if the SessionStart hook didn't run.

Prerequisites

• Credentials: Charlotte AI AgentWorks TOML (~/.cache/crowdstrike-charlotte-ai-agentworks/credentials.toml) OR env vars (FALCON_CLIENT_ID, FALCON_CLIENT_SECRET, optional FALCON_BASE_URL). Run /crowdstrike-charlotte-ai-agentworks:setup if needed.
• API scopes: csrn:charlotte-ai:agent:knowledge-base (read + write)
• Python 3.14+: Auto-managed by the venv setup
• FalconPy 1.6.6+: Provides the native KnowledgeBases, KnowledgeBaseFiles, KnowledgeBaseAuditEvents classes (common/scripts/auth.py enforces a shared 1.6.6+ floor across all skills)

Core Workflow

1. Search/browse KBs by name or description substring → kb_list.py --contains "topic" → table of matches, no exact-syntax guessing needed
2. Query KB IDs by exact/known filter → kb_search.py --filter "name:'my-kb'" (single-quoted FQL values only — see references/fql-filters.md) → returns KB IDs
3. Get KB details → kb_get.py --ids <id1> <id2> → full KB entities
4. Create or update KB → kb_upsert.py --name "..." --description "..." (optional --id for update)
5. Upload file → kb_file_upload.py --kb-id <id> --file <path> --description "..."
6. List/browse files in a KB → kb_files_list.py --kb-id <id> → table of files with size, type, status
7. Download file → kb_file_download.py --kb-id <id> --file-id <id> --output <path>
8. View audit events → kb_audit.py --kb-id <id> --limit 50

Stop after each script; confirm with user before proceeding to the next step.

Script Reference

All scripts support --help for full arg lists and --json for raw JSON output.

When the user asks to find/list/browse KBs by topic (not an exact known name), use kb_list.py --contains "topic", not kb_search.py. kb_search.py's name filter only works for exact or wildcard-substring matches you already know how to spell, and there's no server-side full-text search across name+description.

Usage Examples

Search/browse KBs by topic

../../scripts/python.sh scripts/kb_list.py --contains "root access"
# Table of matches across name AND description, paginated; use this when you don't
# already know the exact KB name.

Query KBs by exact name

../../scripts/python.sh scripts/kb_search.py --filter "name:'Insurance'" --limit 10
# Returns KB IDs. Values MUST be single-quoted -- name:"Insurance" silently matches nothing.

Get KB details

../../scripts/python.sh scripts/kb_get.py --ids abc123-kb-id

Create a new KB

../../scripts/python.sh scripts/kb_upsert.py \
  --name "Insurance Terms & Conditions" \
  --description "Romanian insurance policy documentation"
# Returns KB ID

Update existing KB

../../scripts/python.sh scripts/kb_upsert.py \
  --id abc123-kb-id \
  --description "Updated description..."

Upload file to KB

../../scripts/python.sh scripts/kb_file_upload.py \
  --kb-id abc123-kb-id \
  --file /path/to/document.pdf \
  --description "Insurance policy terms"
# Returns file ID

List files in a KB

../../scripts/python.sh scripts/kb_files_list.py --kb-id abc123-kb-id
# Table: name, description, size, content type, status, last modified, modified by, file ID

Download file from KB

../../scripts/python.sh scripts/kb_file_download.py \
  --kb-id abc123-kb-id \
  --file-id file123 \
  --output ./downloaded-policy.pdf

View KB audit events

../../scripts/python.sh scripts/kb_audit.py \
  --kb-id abc123-kb-id \
  --limit 50
# Shows file uploads, KB updates, etc.

Attach KB to agent (see agents skill)

cd ../agents
../../scripts/python.sh scripts/agent_upsert.py \
  --id <agent-id> \
  --knowledge-base-ids abc123-kb-id

Common Pitfalls / Counter-Rationalizations

Reading Guide

For deep dives, see references/:

Load these on demand — don't read upfront.

FalconPy Native Support

This skill uses native typed FalconPy service classes. Benefits:

• Typed methods: client.EntitiesKnowledgeBasesCreateV1(body={...})
• Auto-parameter validation
• Built-in pagination + error handling