CrowdStrike Charlotte AI AgentWorks Skills

AI coding assistant skills for interacting with CrowdStrike Charlotte AI AgentWorks. Build, manage, invoke, and optimize AI agents.

Getting Started

Prerequisites

• Python 3.14+
• FalconPy 1.6.6+ (auto-installed from PyPI)
• Falcon API OAuth 2.0 client credentials with scopes:
  • charlotte-ai-agent-definition:read — All read operations
  • charlotte-ai-agent-definition:write — All write operations

Installation

Claude Code

Prerequisites: Claude Code CLI installed, Charlotte AI AgentWorks API credentials configured (see Credentials below).

1. Add the marketplace:

   /plugin marketplace add https://github.com/CrowdStrike/agentworks-skills.git
   

   Verify: /plugin marketplace list
2. Install the plugin:

   /plugin install crowdstrike-charlotte-ai-agentworks@agentworks-marketplace
   

   Verify: /plugin list

Updating: refresh the marketplace, then reinstall to pick up the latest release:

/plugin marketplace update agentworks-marketplace
/plugin install crowdstrike-charlotte-ai-agentworks@agentworks-marketplace

Start a new Claude Code session to load the updated skills.

Codex

Prerequisites: Codex CLI installed, Charlotte AI AgentWorks API credentials configured.

1. Add the marketplace:

   codex plugin marketplace add \
     https://github.com/CrowdStrike/agentworks-skills.git
   

   Verify: codex plugin marketplace list
2. Install the plugin:

   codex plugin add \
     crowdstrike-charlotte-ai-agentworks@agentworks-marketplace
   

   Verify: codex plugin list

Updating: refresh the marketplace, then reinstall to pick up the latest release:

codex plugin marketplace upgrade agentworks-marketplace
codex plugin add \
  crowdstrike-charlotte-ai-agentworks@agentworks-marketplace

Start a new Codex thread to load the updated skills.

Local dev

claude --plugin-dir /path/to/agentworks-skills

Credentials

Run /crowdstrike-charlotte-ai-agentworks:setup to configure credentials. The plugin supports two resolution methods:

1. Env vars (CI/overrides): FALCON_CLIENT_ID, FALCON_CLIENT_SECRET, FALCON_BASE_URL
2. TOML profile: ~/.cache/crowdstrike-charlotte-ai-agentworks/credentials.toml

Usage

Example prompts demonstrating the full skill set:

Create a Charlotte AI AgentWorks agent called "Threat Hunter" that analyzes detections

Invoke agent with prompt "Investigate suspicious PowerShell on host XYZ"

Analyze agent for the last 7 days and suggest prompt improvements

The orchestrator skill routes requests to specialized skills based on intent, following a hub-and-spoke pattern.

Skills

Skill	Purpose
agentworks	Primary orchestrator — routes requests to specialized skills
agents	Agent lifecycle (create/update, query, publish, analyze)
invocation	Invoke agents, stream results, get messages, cancel, inspect traces
knowledge-bases	KB CRUD + file upload/download + audit (native FalconPy)
discovery	Query models, tools, templates, versions, spans (native FalconPy)
setup	Credential configuration
foundry-redirect	Points agent/KB requests for a Falcon Foundry app to the crowdstrike-falcon-foundry plugin

Architecture

graph TD
    A[agentworks orchestrator] --> B[agents]
    A --> C[invocation]
    A --> D[knowledge-bases]
    A --> E[discovery]
    B -->|native typed| F[Agents/AgentVersions]
    C -->|native typed| I[AgentInvocation/Stream]
    E -->|native typed| J[Models/Tools/AgentTemplates/AgentVersions/Spans]
    D -->|native typed| G[KnowledgeBases/Files/Audit]
    F --> H["/agentic-studio API"]
    I --> H
    J --> H
    G --> H

FalconPy Integration:

• ✅ Native typed classes throughout: Agents, AgentVersions (agents); AgentInvocation, Stream (invocation, including cancel); KnowledgeBases, KnowledgeBaseFiles, KnowledgeBaseAuditEvents (knowledge-bases); Models, Tools, AgentTemplates, Spans (discovery)

Use Cases

See docs/USE_CASES_VALIDATED.md for validated security operations scenarios:

• Threat hunting agents with Falcon platform integration
• Incident response playbooks with knowledge base attachment
• Agent performance analysis and optimization
• Batch host investigations (ransomware campaigns)
• Trace-based debugging for tool failures

Troubleshooting

Authentication Issues

403 Forbidden — the API client is missing scopes. Grant both charlotte-ai-agent-definition:read and charlotte-ai-agent-definition:write in the Falcon console, then restart so a fresh token is fetched.

Authentication fails — verify credentials with:

python common/scripts/auth.py

Feature Availability

404 Not Found on agent CRUD — Charlotte AI AgentWorks CRUD endpoints may be gated behind a feature flag in your cloud. Contact your CrowdStrike representative for enablement.

Common Issues

See docs/TROUBLESHOOTING.md for comprehensive issue resolution including:

• Span query filter syntax errors
• Tool call failures
• Invocation debugging
• FQL syntax validation

Testing

Verify installation and credentials:

# Test authentication (all 4 FalconPy clients)
python common/scripts/auth.py

# Test knowledge base query (safe read-only)
cd skills/knowledge-bases
../../scripts/python.sh scripts/kb_search.py --limit 5

# Test agent query
cd ../agents
../../scripts/python.sh scripts/agent_search.py --limit 5

OAuth 2.0 Scopes

The API uses a simplified 2-scope model. Both scopes cover all Charlotte AI AgentWorks resources (agents, invocations, knowledge bases, discovery):

Scope	Operations
charlotte-ai-agent-definition:read	• Agent queries and reads • Invocation reads (get messages, stream) • Discovery queries (models, tools, templates, versions, spans) • Knowledge base queries and reads • KB file queries, reads, and audit events
charlotte-ai-agent-definition:write	• Agent create/update/publish • Agent invocation start/cancel • Knowledge base create/update • KB file upload/delete

Contributing

Contributions welcome! See CONTRIBUTING.md for the development workflow, and CODE_OF_CONDUCT.md for our community standards.

Support

See SUPPORT.md for how to get help, and SECURITY.md to report a security vulnerability.

License

MIT — see LICENSE

---

Additional Documentation:

• docs/USE_CASES_VALIDATED.md - Security operations scenarios with expected outputs
• docs/TROUBLESHOOTING.md - Comprehensive issue resolution guide
• references/ - Technical references for Claude Code skills (FQL syntax, span constraints, developer guide)