Update to CrowdStrike AgentWorks

{
  "description": "Manage Charlotte AI AgentWorks knowledge bases. Create/update/query KBs, upload/download files, and view audit events using native FalconPy classes. TRIGGER when user asks to create/query/update a knowledge base, upload files to a KB, download KB files, or view KB audit events. DO NOT TRIGGER for agent creation, agent invocation, or model/tool discovery — use agents, invocation, or discovery skills. DO NOT TRIGGER for knowledge bases defined in a Falcon Foundry app (manifest.yml `ai.knowledge_bases`, `foundry knowledge-bases create`); foundry-redirect handles those.\n",
  "included_files": [
    {
      "relative_path": "references/api-reference.md",
      "size_in_bytes": 3791
    },
    {
      "relative_path": "references/fql-filters.md",
      "size_in_bytes": 2133
    },
    {
      "relative_path": "scripts/kb_audit.py",
      "size_in_bytes": 2416
    },
    {
      "relative_path": "scripts/kb_file_download.py",
      "size_in_bytes": 2185
    },
    {
      "relative_path": "scripts/kb_file_upload.py",
      "size_in_bytes": 2832
    },
    {
      "relative_path": "scripts/kb_files_list.py",
      "size_in_bytes": 4777
    },
    {
      "relative_path": "scripts/kb_get.py",
      "size_in_bytes": 1883
    },
    {
      "relative_path": "scripts/kb_list.py",
      "size_in_bytes": 6524
    },
    {
      "relative_path": "scripts/kb_search.py",
      "size_in_bytes": 2752
    },
    {
      "relative_path": "scripts/kb_upsert.py",
      "size_in_bytes": 3161
    }
  ],
  "name": "knowledge-bases",
  "skill_md_contents": "---\nname: knowledge-bases\ndescription: >\n  Manage Charlotte AI AgentWorks knowledge bases.\n  Create/update/query KBs, upload/download files, and view audit events using native FalconPy classes.\n  TRIGGER when user asks to create/query/update a knowledge base, upload files to a KB,\n  download KB files, or view KB audit events.\n  DO NOT TRIGGER for agent creation, agent invocation, or model/tool discovery —\n  use agents, invocation, or discovery skills.\n  DO NOT TRIGGER for knowledge bases defined in a Falcon Foundry app (manifest.yml `ai.knowledge_bases`,\n  `foundry knowledge-bases create`); foundry-redirect handles those.\nversion: 1.0.1\nupdated: 2026-10-21\ntags: [agentworks, charlotte, knowledge-base, files, audit, falcon]\nauthor: CrowdStrike\nlicense: MIT\ncompatibility: Claude Code >=1.0\nallowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)\nmetadata:\n  category: data-management\n---\n\n# Knowledge Bases\n\n> **Read this first.**\n>\n> You are an AI assistant with expertise in Charlotte AI AgentWorks knowledge base operations.\n> Your role is to help users create, query, update, upload files to, download from, and audit\n> knowledge bases using native FalconPy\n> service classes (`KnowledgeBases`, `KnowledgeBaseFiles`, `KnowledgeBaseAuditEvents`).\n>\n> **IMMEDIATE ACTIONS REQUIRED:**\n> 1. Read this entire skill file before taking any action\n> 2. Verify credentials are configured (TOML profile or env vars)\n> 3. Only use the scripts documented below — never guess API parameters\n> 4. Run scripts via `cd ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-bases && ../../scripts/python.sh scripts/<script>.py`\n> 5. Parse script output and present results clearly to the user\n>\n> **MUST NOT:**\n> - Delete KBs or files (delete operations excluded from v1 scope)\n> - Guess knowledge_base_id or file IDs — always query first\n\n## Running the scripts\n\nAll scripts must be invoked through the managed venv wrapper so dependencies (FalconPy) are available:\n\n```bash\ncd ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-bases\n../../scripts/python.sh scripts/<script_name>.py [args]\n```\n\n- **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.\n- **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.\n\nThe wrapper auto-builds the venv on first use if the SessionStart hook didn't run.\n\n## Prerequisites\n\n- **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.\n- **API scopes**: `csrn:charlotte-ai:agent:knowledge-base` (read + write)\n- **Python 3.14+**: Auto-managed by the venv setup\n- **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)\n\n## Core Workflow\n\n1. **Search/browse KBs by name or description substring** → `kb_list.py --contains \"topic\"` → table of matches, no exact-syntax guessing needed\n2. **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\n3. **Get KB details** → `kb_get.py --ids <id1> <id2>` → full KB entities\n4. **Create or update KB** → `kb_upsert.py --name \"...\" --description \"...\"` (optional `--id` for update)\n5. **Upload file** → `kb_file_upload.py --kb-id <id> --file <path> --description \"...\"`\n6. **List/browse files in a KB** → `kb_files_list.py --kb-id <id>` → table of files with size, type, status\n7. **Download file** → `kb_file_download.py --kb-id <id> --file-id <id> --output <path>`\n8. **View audit events** → `kb_audit.py --kb-id <id> --limit 50`\n\nStop after each script; confirm with user before proceeding to the next step.\n\n## Script Reference\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `kb_list.py` | Browse/search KBs by name+description substring (table output) | `--name-contains`, `--contains` (name OR description), `--modified-since`, `--sort`, `--limit` |\n| `kb_search.py` | Query KB IDs by exact/known FQL filter | `--filter \"name:'...'\"` (single-quoted!), `--limit 100` |\n| `kb_get.py` | Get KB entities by IDs | `--ids <id> [id...]` |\n| `kb_upsert.py` | Create or update a KB | `--name`, `--description`, optional `--id` (update) |\n| `kb_file_upload.py` | Upload file to a KB | `--kb-id`, `--file <path>`, `--description` |\n| `kb_files_list.py` | List files in a KB (table output) | `--kb-id`, `--name-contains` |\n| `kb_file_download.py` | Download file from KB | `--kb-id`, `--file-id`, `--output <path>` |\n| `kb_audit.py` | Query KB audit events | `--kb-id`, `--limit 100` |\n\nAll scripts support `--help` for full arg lists and `--json` for raw JSON output.\n\n**When the user asks to find/list/browse KBs by topic** (not an exact known name), use\n`kb_list.py --contains \"topic\"`, not `kb_search.py`. `kb_search.py`'s `name` filter only works\nfor exact or wildcard-substring matches you already know how to spell, and there's no\nserver-side full-text search across name+description.\n\n## Usage Examples\n\n### Search/browse KBs by topic\n```bash\n../../scripts/python.sh scripts/kb_list.py --contains \"root access\"\n# Table of matches across name AND description, paginated; use this when you don't\n# already know the exact KB name.\n```\n\n### Query KBs by exact name\n```bash\n../../scripts/python.sh scripts/kb_search.py --filter \"name:'Insurance'\" --limit 10\n# Returns KB IDs. Values MUST be single-quoted -- name:\"Insurance\" silently matches nothing.\n```\n\n### Get KB details\n```bash\n../../scripts/python.sh scripts/kb_get.py --ids abc123-kb-id\n```\n\n### Create a new KB\n```bash\n../../scripts/python.sh scripts/kb_upsert.py \\\n  --name \"Insurance Terms & Conditions\" \\\n  --description \"Romanian insurance policy documentation\"\n# Returns KB ID\n```\n\n### Update existing KB\n```bash\n../../scripts/python.sh scripts/kb_upsert.py \\\n  --id abc123-kb-id \\\n  --description \"Updated description...\"\n```\n\n### Upload file to KB\n```bash\n../../scripts/python.sh scripts/kb_file_upload.py \\\n  --kb-id abc123-kb-id \\\n  --file /path/to/document.pdf \\\n  --description \"Insurance policy terms\"\n# Returns file ID\n```\n\n### List files in a KB\n```bash\n../../scripts/python.sh scripts/kb_files_list.py --kb-id abc123-kb-id\n# Table: name, description, size, content type, status, last modified, modified by, file ID\n```\n\n### Download file from KB\n```bash\n../../scripts/python.sh scripts/kb_file_download.py \\\n  --kb-id abc123-kb-id \\\n  --file-id file123 \\\n  --output ./downloaded-policy.pdf\n```\n\n### View KB audit events\n```bash\n../../scripts/python.sh scripts/kb_audit.py \\\n  --kb-id abc123-kb-id \\\n  --limit 50\n# Shows file uploads, KB updates, etc.\n```\n\n### Attach KB to agent (see agents skill)\n```bash\ncd ../agents\n../../scripts/python.sh scripts/agent_upsert.py \\\n  --id <agent-id> \\\n  --knowledge-base-ids abc123-kb-id\n```\n\n## Common Pitfalls / Counter-Rationalizations\n\n| Thought | Reality |\n|---------|---------|\n| \"I'll guess the KB ID\" | **Query first.** KB IDs are UUIDs; guessing fails 100%. Use `kb_search.py` or `kb_list.py`. |\n| \"I'll skip the filter and list all KBs\" | **Always filter.** Unfiltered queries on large CIDs can time out or return truncated results. Use `--filter \"name:'...'\"` or a date range, or use `kb_list.py` which paginates for you. |\n| \"`--filter 'name:\\\"my-kb\\\"'` with double quotes should work\" | **Silently wrong.** FQL string values must be single-quoted (`name:'my-kb'`). Double quotes return 200 OK with zero results — no error — which looks identical to \"no such KB exists.\" See `references/fql-filters.md`. |\n| \"I searched by name and got nothing, so no matching KB exists\" | **Rule out syntax first.** `name` filtering does work on this endpoint (unlike agents), but only exact/wildcard matches with correct quoting. Before concluding nothing exists, either fix the quoting or use `kb_list.py --contains \"...\"` for substring search across name+description. |\n| \"File upload is just POST + JSON body\" | **Multipart/form-data required.** `kb_file_upload.py` uses FalconPy's multipart handling; manual curl won't work without exact boundary formatting. |\n| \"I can delete a KB by setting is_deleted:true\" | **Delete out of scope.** Per v1 plan, no delete operations. KBs persist once created. |\n| \"I'll list a KB's files with `kb_search.py --kb-id`\" | **That flag doesn't exist.** Use `kb_files_list.py --kb-id <id>` instead. |\n| \"I'll pass just `ids` to get file entities\" | **`knowledge_base_id` is also required.** `EntitiesKnowledgeBaseFilesV1(ids=[...])` alone fails with \"knowledge_base_id parameter is required\" — pass both, e.g. `EntitiesKnowledgeBaseFilesV1(knowledge_base_id=kb_id, ids=[...])`. Matches what the Falcon UI itself sends. |\n| \"The native FalconPy class means I don't need auth.py\" | **Auth.py is required.** It builds the clients with credential resolution. Never instantiate `KnowledgeBases()` directly in scripts. |\n\n## Reading Guide\n\nFor deep dives, see `references/`:\n\n| Task | Reference Doc |\n|------|---------------|\n| Full endpoint table (methods, paths, params) | `references/api-reference.md` |\n| FQL filter syntax + confirmed examples (the double-quote trap, substring matching) | `references/fql-filters.md` |\n| OAuth 2.0 flow + scope requirements | `../setup/SKILL.md` |\n\nLoad these on demand — don't read upfront.\n\n## FalconPy Native Support\n\nThis skill uses **native typed FalconPy service classes**. Benefits:\n- Typed methods: `client.EntitiesKnowledgeBasesCreateV1(body={...})`\n- Auto-parameter validation\n- Built-in pagination + error handling\n\n\n"
}