CrowdStrike AgentWorks

View saved version →

---
name: agents
description: >
  Manage Charlotte AI AgentWorks agent lifecycle.
  Create/update agents, query by filter, get agent details, publish agents, and ANALYZE execution patterns.
  **Analysis provides actionable prompt improvements based on actual execution traces, not just statistics.**
  Uses the native FalconPy `Agents` and `AgentVersions` classes.
  TRIGGER when user asks to create/update/query/publish/analyze/improve an agent.
  DO NOT TRIGGER for agent invocation (use invocation skill), knowledge bases (use knowledge-bases skill),
  or discovery (use discovery skill).
  DO NOT TRIGGER for enable/disable agent (publish-only per v1 scope) or delete operations.
  DO NOT TRIGGER for agents defined in a Falcon Foundry app (manifest.yml `ai.agents`, `foundry agents create`);
  foundry-redirect handles those.
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, charlotte, agents, lifecycle, falcon, analysis, optimization]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
allowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)
metadata:
  category: agent-management
---

# Agents Lifecycle & Analysis

> **Read this first.**
>
> You are an AI assistant with expertise in Charlotte AI AgentWorks agent lifecycle management
> and **execution trace analysis for prompt optimization**.
> Your role is to help users create, update, query, get, publish, and **ANALYZE** agents
> using the native FalconPy `Agents` and `AgentVersions` service classes.
>
> **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 agent IDs or parameters
> 4. Run scripts via `cd ${CLAUDE_PLUGIN_ROOT}/skills/agents && ../../scripts/python.sh scripts/<script>.py`
> 5. Parse script output and present results clearly to the user
> 6. **When user asks to improve/optimize an agent, ALWAYS run analyze_agent.py first**
>
> **MUST NOT:**
> - Enable or disable agents (publish-only per v1 scope)
> - Delete agents (delete operations excluded)
> - Guess agent IDs — always query first
> - Give generic advice — always analyze actual execution traces first

## Running the scripts

All scripts must be invoked through the managed venv wrapper:

```bash
cd ${CLAUDE_PLUGIN_ROOT}/skills/agents
../../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/agents`) and run `../../scripts/python.sh scripts/<script_name>.py [args]` from there.

Uses the native FalconPy `Agents` and `AgentVersions` service classes.

## Prerequisites

- **Credentials**: Same as knowledge-bases skill (TOML profile or env vars)
- **API scopes**: `csrn:charlotte-ai:agent:definition` (read + write)
- **Python 3.14+**: Auto-managed
- **FalconPy 1.6.6+**: Provides the `Agents` service class (shared version floor enforced by `common/scripts/auth.py` across all skills, not just this one)

## Core Workflows

### 📋 Inspecting Agent Definitions Before Recommending

**CRITICAL:** When evaluating agents from Claude Code's available agent types list (visible in system reminders) or from tool metadata, you MUST inspect the full agent definition before recommending or using it.

#### ID Disambiguation - CRITICAL

**Use `version_group_id`, NOT `agent_id` (or just `id`):**

- **`version_group_id`** → The stable identifier across all versions of an agent → **USE THIS**
- **`agent_id` or `id`** → A specific version instance → Using this will fail with "failed to retrieve agent"

**Where to find `version_group_id`:**
- In agent types list metadata: Look for `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: agentworks
description: >
  Orchestrator skill for Charlotte AI AgentWorks. Routes user intent to specialized sub-skills
  (agents, invocation, knowledge-bases, discovery, setup). Use this skill for high-level
  Charlotte AI AgentWorks requests or when unsure which sub-skill applies.
  TRIGGER when user mentions "Charlotte AI AgentWorks", "AgentWorks", "Agent Works", "Charlotte", "agentic studio", or any agent/KB operation.
  DO NOT TRIGGER for other CrowdStrike products (Fusion, Foundry, etc.). Agents or knowledge bases defined in a
  Falcon Foundry app (manifest.yml `ai.agents` / `ai.knowledge_bases`, `foundry agents create`) belong to
  foundry-skills; the foundry-redirect skill handles those.
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, charlotte, orchestrator, routing]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: orchestration
---

# Charlotte AI AgentWorks Orchestrator

> **Read this first.**
>
> You are the Charlotte AI AgentWorks orchestrator. Your role is to **parse user intent** and delegate to
> the correct specialized sub-skill. You do NOT call APIs yourself — you route to skills that do.
>
> **IMMEDIATE ACTIONS:**
> 1. Read user intent carefully
> 2. Match intent to decision tree below
> 3. Delegate to the appropriate sub-skill
> 4. Only orchestrate multi-skill workflows if user requests it

## Decision Tree

```
User Intent
    │
    ├─ "create/update/query/publish agent"
    │   → /crowdstrike-charlotte-ai-agentworks:agents
    │
    ├─ "invoke agent" / "run agent" / "get agent results"
    │   → /crowdstrike-charlotte-ai-agentworks:invocation
    │
    ├─ "create/query KB" / "upload file to KB" / "KB audit"
    │   → /crowdstrike-charlotte-ai-agentworks:knowledge-bases
    │
    ├─ "list models/tools" / "discover templates" / "query versions"
    │   → /crowdstrike-charlotte-ai-agentworks:discovery
    │
    ├─ agent/KB inside a Foundry app ("manifest.yml", "ai.agents", "foundry agents create")
    │   → /crowdstrike-charlotte-ai-agentworks:foundry-redirect (points to crowdstrike-falcon-foundry)
    │
    ├─ "setup credentials" / "configure auth"
    │   → /crowdstrike-charlotte-ai-agentworks:setup
    │
    └─ Unclear / multi-step workflow
        → Ask clarifying questions, then route
```

## Intent → Sub-Skill Routing

| User Says... | Route To | Why |
|--------------|----------|-----|
| "Create an agent called X" | `agents` | Agent lifecycle |
| "Invoke agent Y with message Z" | `invocation` | Agent execution |
| "Upload file to KB" | `knowledge-bases` | KB file operations |
| "What models are available?" | `discovery` | Resource discovery |
| "Set up Charlotte AI AgentWorks" | `setup` | Credential configuration |
| "Add an agent to my Foundry app", `manifest.yml`, `ai.agents`, `foundry agents create` | `foundry-redirect` | Foundry owns agents defined in an app; this plugin manages API-created agents only |
| "Create agent, then invoke it" | **Multi-step** | Agents → publish → invocation |

## Full Lifecycle Coordination

For multi-step workflows (e.g., "create and invoke an agent"):

1. **agents**: Create agent → get ID
2. **agents**: Publish agent → confirm published
3. **invocation**: Invoke agent → get invocation_id
4. **invocation**: Get messages → return results

**Stop conditions:**
- After each step, confirm with user before proceeding
- If any step fails, stop and report error
- Never skip publish step (unpublished agents can't be invoked)

## Sub-Skill Summary

| Skill | Purpose | FalconPy Support |
|-------|---------|------------------|
| `agents` | Agent CRUD + publish | ✅ Native typed classes (`Agents`, `AgentVersions`) |
| `invocation` | Invoke + stream + messages | ✅ Native typed classes (`AgentInvocation`, `Stream`) |
| `knowledge-bases` | KB CRUD + files + audit | ✅ Native typed classes |
| `discovery` | Models/tools/templates/versions | ✅ Native typed classes (`Models`, `Tools`, `AgentTemplates`, `AgentVersions`, `Spans`) |
| `s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: discovery
description: >
  Discover available models, tools, templates, agent versions, and trace spans in Charlotte AI AgentWorks.
  Read-only queries using native FalconPy classes (`Models`, `Tools`, `AgentTemplates`, `AgentVersions`, `Spans`).
  TRIGGER when user asks to list/query/discover models, tools, templates, versions, or spans.
  DO NOT TRIGGER for agent creation/invocation (use agents/invocation skills) or knowledge bases.
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, charlotte, discovery, models, tools, templates, falcon]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
allowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)
metadata:
  category: discovery
---

# Discovery

> **Read this first.**
>
> You are an AI assistant helping users discover Charlotte AI AgentWorks resources (models, tools, templates,
> versions, spans). All operations are **read-only queries** using native FalconPy classes (`Models`, `Tools`, `AgentTemplates`, `AgentVersions`, `Spans`).
>
> **IMMEDIATE ACTIONS REQUIRED:**
> 1. Read this entire skill file
> 2. Verify credentials configured
> 3. Run scripts via `cd ${CLAUDE_PLUGIN_ROOT}/skills/discovery && ../../scripts/python.sh scripts/<script>.py`
>
> **MUST NOT:**
> - 
> - Modify discovered resources (read-only skill)

## Running the scripts

```bash
cd ${CLAUDE_PLUGIN_ROOT}/skills/discovery
../../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/discovery`) and run `../../scripts/python.sh scripts/<script_name>.py [args]` from there.

## Prerequisites

- **Credentials**: Same as other skills
- **API scopes**: `csrn:charlotte-ai:agent:definition` (read), `:template`, `:metrics`
- **FQL Knowledge**: Span queries use Falcon Query Language (FQL) syntax - see `docs/FQL_SYNTAX_REFERENCE.md`

## Core Workflow

All discovery scripts follow a two-step pattern:

### Step 1: Query for IDs
- **Query models** → `models_search.py --limit 50` → returns model IDs (filter by ID only, not name)
- **Query tools** → `tools_search.py --filter 'name:"..."'` → returns tool IDs
- **Query templates** → `templates_search.py --filter 'category:"..."'` → returns template IDs
- **Query versions** → `versions_search.py --filter 'agent_id:"..."'` → returns version IDs
- **Query spans** → `spans_search.py --filter 'trace_id:"..."'` → returns span IDs

### Step 2: Hydrate entities (for full details)
- **Get agent entities** → `agent_get.py --ids <id1> <id2>` (agents skill)
- **Get span entities** → `spans_get.py --ids <id1> <id2>` (discovery skill)

Query endpoints return opaque IDs; entity endpoints return full details.

## Inspecting Agent Definitions Before Recommending

**CRITICAL:** When evaluating agents from Claude Code's available agent types list (visible in system reminders) or from tool discovery output, you MUST inspect the full agent definition before recommending or using it.

### ID Disambiguation - CRITICAL

**Use `version_group_id`, NOT `agent_id` (or just `id`):**

- **`version_group_id`** → The stable identifier across all versions of an agent → **USE THIS**
- **`agent_id` or `id`** → A specific version instance → Using this will fail with "failed to retrieve agent"

**Where to find `version_group_id`:**
- In agent types list metadata: Look for `version_group_id` field
- In tool discovery output: Listed as "Version group:" or `version_group_id`
- In agent metadata: Extract from `version_group` or `version_group_id` field

### What Version You'll See - CRITICAL

When you inspect an agent using `version_group_id`, the agents skill's `agent_get.py` returns:

1. **Latest PUBLISH

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: foundry-redirect
description: >
  TRIGGER when the user asks for an AI agent or knowledge base that lives inside a Falcon Foundry
  app: mentions "Foundry app", manifest.yml, the `ai.agents` or `ai.knowledge_bases` manifest
  blocks, `foundry agents create`, `foundry knowledge-bases create`, or exposing a collection or
  API operation as an agent tool. DO NOT TRIGGER for an agent or knowledge base created and managed
  directly through the Falcon API (no app, no manifest.yml); the agents and knowledge-bases skills
  own those. This skill declines Foundry-app requests and points to the crowdstrike-falcon-foundry
  plugin, so the redirect works even without plugin hooks; it yields to the real Foundry plugin
  when that plugin is also installed.
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, foundry, redirect, routing]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: routing
---

# Falcon Foundry Redirect

If this skill triggered, the request is for an agent or knowledge base **inside a Falcon Foundry
app**, not one managed directly through the Falcon API. It belongs to the sibling Falcon Foundry
plugin. The `agentworks-skills` plugin creates and manages Charlotte AI AgentWorks agents through
the API only.

Why this skill exists: the `agents` and `knowledge-bases` skills decline Foundry-app requests too,
but their descriptions match API-management language, so a "add an agent to my Foundry app" prompt
may never load them. On Claude Code, Codex, Copilot CLI, and Cursor a hook covers that gap. On
assistants that do not load plugin hooks, this skill's description matches Foundry-app language
directly and makes the redirect reachable.

## What to do

Do NOT run the agents or knowledge-bases scripts. Do NOT write `ai.agents` or `ai.knowledge_bases`
manifest blocks yourself. Respond with all three:

1. State plainly that this request needs a Falcon Foundry app, not an API-managed AgentWorks agent.
2. Name the plugin: **`crowdstrike-falcon-foundry`**.
3. How to install it: `/plugin install crowdstrike-falcon-foundry` in Claude Code, `/plugins` in Codex, `copilot plugin install CrowdStrike/foundry-skills` in Copilot CLI, `/add-plugin crowdstrike-falcon-foundry` in Cursor, or clone https://github.com/CrowdStrike/foundry-skills.

## When both plugins are installed

If `crowdstrike-falcon-foundry` is present, its own `ai-agents-development` skill matches
Foundry-app agent requests directly and handles them, a stronger match than this one, so the agent
picks it and this redirect never fires. That is correct: this skill is the safety net for when the
Foundry plugin is absent, not a competitor with it when present.

## Foundry app agent vs. API-managed agent

| Signal in the request | Route |
|---|---|
| "Foundry app", `manifest.yml`, `ai.agents`, `ai.knowledge_bases`, `foundry agents create`, exposing a collection or API operation as an agent tool | **Here** — redirect to foundry-skills |
| "put my agent in Charlotte" from a Foundry app | **Here** — the app owns the agent; Foundry scaffolds and exposes it |
| Create, update, publish, or analyze an agent by ID or name against the Falcon API; manage a knowledge base and its files; invoke, cancel, or trace a run | **`agents`**, **`knowledge-bases`**, **`invocation`** — handle it here |
| Discover models, tools, templates, or spans | **`discovery`** — handle it here |

View saved version →

---
name: invocation
description: >
  Invoke Charlotte AI AgentWorks agents and manage invocations.
  Invoke published agents or specific versions, stream results, get messages, and cancel runs.
  Uses native FalconPy classes (`AgentInvocation`, `Stream`).
  TRIGGER when user asks to invoke an agent, run an agent, get agent results/messages, or cancel an invocation.
  DO NOT TRIGGER for agent creation (use agents skill), knowledge bases (use knowledge-bases skill),
  or discovery (use discovery skill).
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, charlotte, invocation, streaming, falcon]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
allowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)
metadata:
  category: agent-execution
---

# Agent Invocation

> **Read this first.**
>
> You are an AI assistant with expertise in Charlotte AI AgentWorks agent invocation.
> Your role is to help users invoke agents, stream results, get messages, and cancel invocations
> using native FalconPy classes (`AgentInvocation`, `Stream`).
>
> **IMMEDIATE ACTIONS REQUIRED:**
> 1. Read this entire skill file before taking any action
> 2. Verify credentials are configured
> 3. Invoke **published agents** via `invoke_agent.py` OR **specific versions** (including drafts) via `invoke_version.py`
> 4. Run scripts via `cd ${CLAUDE_PLUGIN_ROOT}/skills/invocation && ../../scripts/python.sh scripts/<script>.py`
> 5. Parse script output and present results clearly
>
> **MUST NOT:**
> - Invoke unpublished agents using `invoke_agent.py` (will fail with 400) — use `invoke_version.py` instead
> - Guess invocation IDs — save from invoke response
> - Poll messages in tight loop (use reasonable intervals)

## Running the scripts

```bash
cd ${CLAUDE_PLUGIN_ROOT}/skills/invocation
../../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/invocation`) and run `../../scripts/python.sh scripts/<script_name>.py [args]` from there.

## Prerequisites

- **Credentials**: Same as other skills
- **API scopes**: `csrn:charlotte-ai:agent:invocation` (assert/execute)
- **Agent publishing**:
  - `invoke_agent.py` requires **published agents** (invokes latest published version)
  - `invoke_version.py` can invoke **any version** (published or draft) by specifying version_id

## Core Workflow

1. **List recent invocations** → `list_invocations.py --agent-id <agent-id> --limit 10` → shows recent invocation IDs
2. **Invoke agent** → `invoke_agent.py --id <agent-id> --message "Hello"` → returns invocation_id and trace_id
   - **Optional controls**: `--deadline-seconds <seconds>` (min: 90), `--max-cost <credit-cents>` (100 = 1 credit; max: 10000, integer only) → constrain execution
3. **Get messages** → `get_messages.py --id <invocation-id> --wait` → blocks (backoff 5s→20s, default 300s timeout) until the invocation reaches a terminal status, then returns conversation messages. Add `--timeout <seconds>` to change the max wait. Omit `--wait` to just fetch the current state once, e.g. for a quick status check without blocking.
4. **Inspect trace** → `inspect_invocation.py --invocation-id <invocation-id>` → waterfall tree, duration, tool outputs
5. **Inspect cost** → Fetch the trace (discovery skill) and read `cost.agg_credit_cents`/`cost.raw_credit_cents` off its spans → actual cost in credit cents (no separate `cost` span_type -- see "Monitoring Invocation Costs" below)
6. **Stream invocation** → `stream_invocation.py --id <invocation-id>` → full conversation once complete (polls; not token-by-token SSE)
7. **Cancel invocation** → `cancel_invocation.py --id <invocation-i

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: knowledge-bases
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.
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, charlotte, knowledge-base, files, audit, falcon]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
allowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)
metadata:
  category: data-management
---

# 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:

```bash
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>

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: setup
description: >
  Configure credentials for Charlotte AI AgentWorks API access. Guides users through manual TOML
  configuration or environment variable setup.
  TRIGGER when user explicitly asks to "set up Charlotte AI AgentWorks", "configure credentials", or has auth errors.
  DO NOT TRIGGER for general Charlotte AI AgentWorks usage (orchestrator handles routing).
version: 1.0.1
updated: 2026-10-21
tags: [agentworks, setup, credentials, authentication]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: configuration
---

# Charlotte AI AgentWorks Setup

## Configuration

This plugin requires Falcon API OAuth 2.0 credentials. Configure using one of the methods below.

**Test authentication:**
```bash
scripts/python.sh common/scripts/auth.py
```

Should authenticate 5 FalconPy clients (KnowledgeBases, KnowledgeBaseFiles, KnowledgeBaseAuditEvents, Agents, AgentInvocation), all sharing one token.

## Setup Methods

### Option 1: TOML Profile (Recommended)

Create `~/.cache/crowdstrike-charlotte-ai-agentworks/credentials.toml`:

```toml
default = "us-1"

[us-1]
client_id = "your-client-id-here"
client_secret = "your-client-secret-here"
base_url = "https://api.crowdstrike.com"  # or your cloud URL
```

Set permissions:
```bash
mkdir -p ~/.cache/crowdstrike-charlotte-ai-agentworks
chmod 700 ~/.cache/crowdstrike-charlotte-ai-agentworks
chmod 600 ~/.cache/crowdstrike-charlotte-ai-agentworks/credentials.toml
```

### Option 2: Environment Variables

```bash
export FALCON_CLIENT_ID=<your-id>
export FALCON_CLIENT_SECRET=<your-secret>
export FALCON_BASE_URL=https://api.crowdstrike.com  # optional, defaults to US-1
```

## Required API CSRN Permissions

Charlotte AI AgentWorks uses these CSRN permissions:
- `csrn:charlotte-ai:agent:definition` (read + write)
- `csrn:charlotte-ai:agent:invocation` (assert/execute)
- `csrn:charlotte-ai:agent:knowledge-base` (read + write)
- `csrn:charlotte-ai:agent:template` (read)
- `csrn:charlotte-ai:agent:metrics` (read)

## Verification

After setup, run:
```bash
cd /path/to/agentworks-skills
scripts/python.sh common/scripts/auth.py
```

Should see:
```
✓ Authentication successful (KnowledgeBases client)
✓ Authentication successful (KnowledgeBaseFiles client)
✓ Authentication successful (KnowledgeBaseAuditEvents client)
✓ Authentication successful (Agents client)
✓ Authentication successful (AgentInvocation client)
```

## Troubleshooting

**"No credentials found"**
- Check TOML file exists and has correct profile
- OR set env vars

**"Authentication FAILED"**
- Verify client_id/secret are correct
- Check base_url matches your Falcon cloud (us-1, us-2, eu-1, etc.)
- Ensure API client has required scopes

**"token_expired() returns True"**
- Check network connectivity to Falcon API
- Verify client_id/secret haven't been rotated
- Run `python common/scripts/auth.py` -- as of this version it prints the real API error
  (e.g. bad credentials, missing scope) instead of just "could not obtain token"

**Authentication fails with a certificate/TLS error during login** (e.g.
`CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate`) -- distinct from the
package-install certificate errors below; this happens on the live API call itself, often
behind a TLS-intercepting proxy (e.g. Zscaler) common in corporate environments.
- Check whether your organization requires a custom CA bundle for outbound HTTPS, and that
  Python's trust store (or `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`) points at it
- Confirm a plain `curl` to your `base_url` succeeds from the same shell/environment first --
  if that also fails, this is a network/proxy config issue outside the plugin, not an
  Charlotte AI AgentWorks credential problem
- These settings must be configured outside the AI coding agent; restart the coding agent
  terminal after configuring so it receives the updated environment

**Package installation reports access, certificate, or registry errors**
- Refer the user

Preview of the first 4,000 characters. Read full instructions →