Falcon Fusion Skills
AI coding assistant skills for building CrowdStrike Falcon Fusion workflows. Go from a natural language prompt to a working Fusion workflow — discover real action IDs from the live API, author the YAML, validate it against the platform schema, import it to a CID, and trigger and monitor its execution.
fusion-skills is a community-driven, open source project, not a CrowdStrike product. As such, it carries no formal support, expressed or implied.
Getting Started
Prerequisites
- CrowdStrike Account with the Workflow API scope (plus NGSIEM Lookup Files for the lookup-files skill)
- AI Coding Assistant: Claude Code, Codex, Copilot CLI, Cursor, Antigravity CLI, or any tool that can read local reference documentation
- jq for the skill-routing hooks (without it, the hooks stay silent)
Install
| Assistant | Command | Marketplace |
|---|
| Claude Code | /plugin install crowdstrike-falcon-fusion | Anthropic |
| Codex | codex plugin add crowdstrike-falcon-fusion@openai-api-curated | OpenAI |
| Copilot CLI | copilot plugin install CrowdStrike/fusion-skills | GitHub |
| Cursor | /plugins (CLI) or /add-plugin crowdstrike-falcon-fusion (IDE) | Cursor |
| Antigravity CLI | agy plugin install https://github.com/CrowdStrike/fusion-skills | Google |
[!NOTE]
Codex has two install paths depending on how you signed in. The command above installs from the curated CLI marketplace, which API-key and Amazon Bedrock sessions load. If you authenticated Codex with a ChatGPT account, that marketplace isn't loaded — instead run /plugins inside Codex, search for crowdstrike, and install from the results.
In a live-tenant run, all five assistants (Claude Code, Codex, Copilot CLI, Cursor, and Antigravity CLI) each authored a valid workflow from the example prompt below and imported it to the tenant.
These skills follow the Agent Plugins format, with a root plugin.json and a Codex .codex-plugin/plugin.json so the non-Claude assistants can discover them. See the blog post for a full walkthrough.
git clone https://github.com/CrowdStrike/fusion-skills.git
| Assistant | Command |
|---|
| Claude Code | claude --plugin-dir /path/to/fusion-skills |
| Copilot CLI | copilot --plugin-dir /path/to/fusion-skills |
| Cursor | agent --plugin-dir /path/to/fusion-skills --trust |
| Antigravity CLI | agy plugin install /path/to/fusion-skills |
Codex has no --plugin-dir; it discovers skills from ~/.agents/skills/, one symlink per skill (Copilot CLI and Cursor can use this directory too):
mkdir -p ~/.agents/skills
for skill in /path/to/fusion-skills/skills/*; do
ln -s "$skill" ~/.agents/skills/
done
~/.agents/skills/ is a flat, shared namespace: fusion-skills' skill names don't overlap with foundry-skills', so both can be symlinked in together. A marketplace or --plugin-dir install namespaces the skills as crowdstrike-falcon-fusion:<skill> and sidesteps the question entirely. Restart the assistant after symlinking; some prompt for authentication on first run.
Credentials
These skills authenticate with a Falcon API client. In the console, go to Support and resources > Client Management > Create API client, grant the Workflow scope (read and write), and, for the lookup-files skill, also NGSIEM Lookup Files (read and write). Copy the client ID and secret shown once on creation, then configure them below.
Configure credentials once. Run the interactive setup skill — it writes a profile to ~/.cache/crowdstrike-falcon-fusion/credentials.toml:
/crowdstrike-falcon-fusion:setup
For CI or a one-off override, set environment variables instead:
export FALCON_CLIENT_ID=your_client_id_here
export FALCON_CLIENT_SECRET=your_client_secret_here
# Optional on US-1, US-2, and EU-1 (FalconPy discovers the region). Set it for any other cloud, such as US-3 or GovCloud:
# export FALCON_BASE_URL=https://api.us-3.crowdstrike.com # US-GOV-1: https://api.laggar.gcw.crowdstrike.com
Credentials come from environment variables (checked first) or the TOML profile, and are never hardcoded. Either source can hold a 1Password secret reference (op://<vault>/<item>/<field>) instead of the client ID or secret, which auth.py reads with the 1Password CLI so the secret stays off disk. On a network that re-signs TLS traffic, set a profile's ca_bundle to your organization's CA bundle. See the setup skill for both. Verify your setup:
python common/scripts/auth.py
Other Tools
These skills are plain markdown files. Any AI coding assistant that can read local files can use them. See AGENTS.md for the full development guide, or point your tool at the skills/ directory and start with workflows/SKILL.md as the entry point.
Usage
Example prompt
This prompt exercises the full lifecycle: action discovery, event queries, parallel HTTP Action enrichment, an LLM completion action, and validation:
Generate a Falcon Fusion workflow that will trigger from a Falcon Next-Gen SIEM detection. The workflow should hydrate the detection using an event query to get the full details of the detection. If a user, host, domain, url, file indicator, or ip indicator is found, enrich each in parallel using HTTP calls to VirusTotal or DomainTools. Summarize the enrichment across all the threat intelligence providers using an LLM completion action and then send an email formatted in HTML.
Describe what you want in plain language. You don't need to name a skill. The orchestrator picks the right one.
How skill routing works
Repository-backed installs in Claude Code, Codex, Copilot CLI, and Cursor include hooks that ensure the right skills get used. Codex requires reviewing and trusting bundled hooks through /hooks before they run. Cursor loads them from .cursor-plugin/plugin.json:
-
UserPromptSubmit hook — Matches Fusion phrases ("fusion workflow", "build a playbook", "deploy to CID") or an action verb paired with a Fusion noun ("automate crowdstrike actions"). When matched, it injects a non-blocking advisory steering toward the workflows orchestrator skill.
-
PreToolUse hook — While Fusion intent is active, injects a non-blocking reminder to use the Fusion workflows skill. All tools remain available; nothing is blocked.
-
PreToolUse hook (cross-plugin bridge) — Advisory only. If a request needs a Foundry app (UI, functions, collections, manifest.yml), it suggests the sibling crowdstrike-falcon-foundry plugin. It never blocks a skill.
The workflows orchestrator is the entry point: you say what you want, and it routes to authoring (discover actions, write and validate YAML), deployment (import and release to a CID), and execution (trigger and monitor). Hooks observe prompts and tool I/O to keyword-match Fusion actions; no data leaves the session.
Local Codex installs made with skill symlinks, and other assistants that do not load bundled hooks, route from the skill descriptions instead.
Skills
One plugin provides six skills: an orchestrator, four focused sub-skills, and a Foundry-app redirect.
| Skill | Purpose |
|---|
workflows | Primary orchestrator — routes intent and coordinates the full workflow lifecycle |
authoring | Action discovery (action_search.py), YAML authoring, CEL expressions, schema validation (validate.py) |
deployment | Duplicate check, import to CID, release, version management |
execution | Trigger workflows with payloads, monitor status, tail logs, debug failures |
lookup-files | Manage Falcon Next-Gen SIEM lookup files (CSV/JSON/TXT) for CQL match() queries |
foundry-redirect | Declines Falcon Foundry app requests (UI, functions, collections, manifest.yml) and points to the crowdstrike-falcon-foundry plugin |
Architecture
The skills follow a hub-and-spoke pattern. workflows is the orchestrator that parses your intent and delegates each phase to a sub-skill; it never writes YAML or calls APIs itself. Sub-skills share API authentication through common/scripts/auth.py.
graph TD
O["workflows<br/>(Orchestrator)"]
O --> AU["Authoring<br/>(discover, write, validate)"]
O --> DE["Deployment<br/>(import, release)"]
O --> EX["Execution<br/>(trigger, monitor)"]
O --> LF["Lookup Files<br/>(NGSIEM)"]
AU --> DE
DE --> EX
style O fill:#6366f1,stroke:#4f46e5,color:#fff
style LF fill:#f59e0b,stroke:#d97706,color:#fff
A typical lifecycle: authoring produces a validated YAML file → deployment imports it and returns a definition_id → execution triggers it and returns an execution_id. Each phase depends on the previous one's output.
skills/
workflows/ orchestrator — decision tree, lifecycle coordination
authoring/ action discovery, YAML authoring, validation
deployment/ import, release, version management
execution/ trigger, monitor, debug
lookup-files/ Next-Gen SIEM lookup file management
setup/ interactive credential setup
common/ shared API auth (auth.py)
use-cases/ pattern-matchable workflow scenarios
hooks/ intent routing + cross-plugin advisories
Quick Start
A workflow goes from idea to running in five steps. The orchestrator coordinates them; here is the shape:
- Discover actions — find real action IDs from the live catalog:
python skills/authoring/scripts/action_search.py --search "contain"
- Author the YAML — write the workflow with a trigger and actions, each with a
version_constraint. Never use placeholder IDs.
- Validate — check structure against the Charlotte JSON schema:
python skills/authoring/scripts/validate.py my-workflow.yml
- Deploy — check for duplicates, then import and release to your CID:
python skills/deployment/scripts/query_workflows.py --search "My Workflow"
python skills/deployment/scripts/import_workflows.py my-workflow.yml
python skills/deployment/scripts/release_workflow.py --id <definition_id>
# Remove a test/duplicate workflow when you're done with it:
python skills/deployment/scripts/delete_workflow.py --id <definition_id>
- Execute — trigger and monitor:
python skills/execution/scripts/trigger_workflow.py --id <definition_id> --params '{"device_id":"..."}'
python skills/execution/scripts/monitor_execution.py --execution-id <execution_id>
Use Cases
The use-cases/ directory contains pattern-matchable workflow scenarios. Some are drawn from CrowdStrike Tech Hub blog posts; others are grounded directly in the bundled example workflows and the community "Workflow Wednesday" series. Each names the sub-skills it needs and cites its source.
Grounded in bundled example workflows:
Platform patterns:
Recommended Companion: Superpowers
These skills pair well with obra/superpowers, which adds structured planning, TDD discipline, debugging, and code review workflows. Fusion skills handle the Fusion-specific action discovery, schema, and platform knowledge while superpowers provides general software engineering best practices.
Unlike some plugins, fusion-skills does not block or redirect superpowers:brainstorming; its cross-plugin hook is advisory only. Use superpowers freely alongside it.
Troubleshooting
Skills not invoked
If your assistant doesn't use Fusion skills automatically, phrase your prompt with a clear Fusion noun and action verb (e.g., "create a fusion workflow", "build a playbook that…"). You can also say "Use the fusion workflows skill" at any point to redirect.
Authentication failures
python common/scripts/auth.py # Verify credentials resolve and a token is issued
/crowdstrike-falcon-fusion:setup # Re-run interactive credential setup (Claude Code)
Confirm FALCON_CLIENT_ID and FALCON_CLIENT_SECRET are set in your environment or TOML profile, and, on any cloud other than US-1, US-2, and EU-1 (such as US-3 or GovCloud), that FALCON_BASE_URL (or the profile's base_url) points at your cloud. FalconPy discovers those three on its own.
If the credentials are right but the self-test still reports "could not obtain token", a TLS-inspecting proxy may be re-signing traffic. Set ca_bundle in the profile to your organization's CA bundle (PEM). The self-test's CA bundle line shows which one is in use. If the plugin's Python setup fails because public PyPI is blocked, set PIP_INDEX_URL (or UV_DEFAULT_INDEX) to your package mirror and run scripts/setup-python-venv.sh again.
Stale action cache
Action discovery caches results locally. If a newly shipped action type (e.g., a new native action) doesn't appear, refresh the cache:
python skills/authoring/scripts/action_search.py --clear-cache
python skills/authoring/scripts/action_search.py --search "contain"
Workflow won't execute
A workflow must be released before it can be triggered. If trigger_workflow.py reports the workflow isn't runnable, confirm release_workflow.py completed for that definition_id. HTTP Actions also require their credential config (config_id) to already exist in the target CID.
Testing
Several scripts validate changes at different levels. All require macOS or Linux (bash).
Unit tests (Python)
The Python scripts have a comprehensive pytest suite that mocks all API calls, so no CrowdStrike credentials are needed. Run it in a virtual environment:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-test.txt
pytest tests/ -v
Add --cov to see coverage (CI enforces 90%):
pytest tests/ --cov=common/scripts --cov=skills --cov=scripts --cov-report=term-missing
Fast checks (no API calls)
./test-hooks.sh # Unit-tests the skill router and cross-plugin bridge hooks
./test-validate.sh # Validates SKILL.md frontmatter, Python syntax, and reference docs
./test-scorecard-parser.sh # Unit-tests the verify-workflows.sh scorecard (status/PASS/FAIL parsing)
./test-skill-scorecard.sh # Unit-tests the test-skill.sh scorecard (authoring anti-patterns + deploy-churn counting)
Run these after any hook, skill, or script change. They're fast and need no credentials.
Skill test (single run)
./test-skill.sh --runs 1 # Quick single run
./test-skill.sh --runs 5 # Default: 5 runs
./test-skill.sh --skip-deploy # Author + validate only (no live API)
./test-skill.sh --release-check # Also release each deployed workflow
./test-skill.sh --plugin-dir /path # Use a different plugin directory
Runs the canonical prompt end-to-end: the skill authors a workflow, validates it (skills/authoring/scripts/validate.py), and optionally imports it (skills/deployment/scripts/import_workflows.py). Results are collected as structured JSON.
Verify workflows
./verify-workflows.sh # full run: script phase + browser phase
./verify-workflows.sh --skip-browser # script phase only (API, no browser)
./verify-workflows.sh --skip-deploy # validate only (no credentials)
Two-phase verification that workflow YAML files actually work. Phase 1 (script-based) runs each workflow through validation, import, trigger, and monitoring using the fusion-skills Python scripts. Phase 2 (browser) drives the Falcon console to configure the VirusTotal credential, publish, and execute — the part the API cannot do — and runs by default, prompting for a console login. A workflow only passes if every phase that ran succeeds.
Multi-assistant smoke test
./test-assistants.sh # smoke-test every installed assistant in parallel
./test-assistants.sh --include codex # only these (comma-separated)
./test-assistants.sh --e2e # author, validate, and import for real
./test-assistants.sh --judge # confirm the last --e2e run against the tenant
Gives each installed assistant (Claude Code, Codex, Copilot CLI, Cursor, Antigravity CLI) the canonical prompt and reads back a fixed plain-text report — which skills loaded, which scripts ran, and any blocker — so a clean timeout is never mistaken for a pass. Before testing it isolates skill sources so results are unambiguous: it disables installed Fusion plugins where it can, moves every ~/.agents/skills/ symlink aside, and for Antigravity, which only loads its own plugin directory, parks the installed Fusion plugin and symlinks the working tree in its place. Everything is restored on exit, including on Ctrl-C, via scripts/skill-isolation.sh and scripts/agy-plugin-swap.sh, and Antigravity is skipped rather than tested against the installed copy if the swap can't be made. --e2e requires a real workflow definition id, and --judge confirms that id against the tenant with query_workflows.py --list and reads the authored YAML for each pipeline stage — it never trusts the transcript.
A/B test (baseline vs local branch)
./run-ab-test.sh # baseline (main) vs local skills, 5 runs each
./run-ab-test.sh 3 # 3 runs per phase
./run-ab-test.sh --ref v1.0.0 # compare local branch against a specific tag
./run-ab-test.sh --skip-deploy # author + validate only (no live API)
./run-ab-test.sh --release-check # also release each deployed workflow
Compares baseline ref skills (RED) against local branch skills (GREEN), with smart baseline caching. Use tail-test.sh in another terminal to watch the active run's tool calls in real time.
DEPLOYED in the scorecard means the workflow imported, which doesn't prove it will release. Add --release-check when a change could affect whether workflows release, such as edits to triggers, templates, or validate.py. It releases each run's workflow and adds a Released row to the comparison. Released workflows are live until the cleanup deletes them a few seconds later, so an NG-SIEM workflow could fire on a real detection in that window. That's why the flag is opt-in.
Tip: Wrap long-running tests with caffeinate -i to prevent macOS from sleeping mid-run:
caffeinate -i ./run-ab-test.sh --fresh --release-check 5
Contributing
The skills improve every time someone uses them to build a workflow. If you hit a rough edge or find that your assistant struggles with a particular pattern, you can teach the skills to handle it better.
Use the skills, then improve them
- Clone this repo and configure your AI coding assistant (see Getting Started)
- Try the example prompt above
- Watch for patterns where the assistant struggles, retries, or produces incorrect output
- At the end of the session, ask it to fix the skills directly:
What did you learn from this session that could improve the Fusion skills?
Clone https://github.com/CrowdStrike/fusion-skills.git,
create a branch, update the skills with this knowledge, and
create a PR on GitHub.
This captures the learning so the next session is faster and uses fewer tokens.
Development workflow
- Clone the repo (see Getting Started)
- Edit skill files in
skills/*/SKILL.md or scripts in skills/*/scripts/
- Run
pytest tests/ (for script changes) and ./test-hooks.sh / ./test-validate.sh to validate
- Test with
./test-skill.sh --runs 1 for a quick end-to-end check
- Run
./run-ab-test.sh 1 to compare against main before opening a PR
See CONTRIBUTING.md for the full guidelines.
Release process
./release.sh
This walks you through a semantic version bump (major/minor/patch), updates the version across the plugin manifests (.claude-plugin/plugin.json, marketplace.json, the root plugin.json, .codex-plugin/plugin.json, and .cursor-plugin/plugin.json), the README badge, and the CHANGELOG, then creates a release branch and PR. After the PR is approved and merged, create a draft GitHub release to tag main:
gh release create v<version> --target main --title "v<version>" --generate-notes --draft
Review and edit the notes at github.com/CrowdStrike/fusion-skills/releases, then click Publish when ready.
After publishing the release, update the marketplaces that pin a snapshot. Build and upload the OpenAI skills-only bundle with ./release.sh --bundle v<version>, email the Cursor marketplace team to re-index the listing, and open a PR to github/awesome-copilot that bumps the version, ref, and sha of the crowdstrike-falcon-fusion entry. release.sh prints the exact steps when it finishes.
Cross-Plugin: Foundry Apps
fusion-skills builds standalone workflows, authored, imported, and executed directly against Fusion with no app wrapper. When a workflow needs to be wrapped in a Falcon Foundry app (custom UI, serverless functions, collections, or a manifest.yml), use the sibling plugin (foundry-skills):
claude plugin install crowdstrike-falcon-foundry
The two plugins detect each other and advise the right path. Use fusion-skills for standalone workflows with live action discovery; use foundry-skills for the full app lifecycle. Neither requires the other to function.
Acknowledgments
fusion-skills builds on security-skills by Paul Price (@eth0izzle), an MIT-licensed community Claude Code plugin for Fusion workflow automation. We contributed the Charlotte JSON schema reference, the structural validator, and Content Library workflow examples upstream; fusion-skills is the CrowdStrike-branded, multi-tool evolution of that work.
License
MIT — see LICENSE for details.
