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

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 PUBLISHED version (if one exists) ← Most common case
2. Latest version (if no published version exists) ← Draft only

Important implications:

• Modifying a published agent creates a DRAFT version → The draft is NOT returned
• Inspection shows production behavior → You see what's actually running, not work-in-progress
• Draft changes are invisible until published → Recent modifications won't appear until published

Workflow for Agent Inspection:

1. Extract version_group_id (NOT agent_id or id) from the metadata
2. Use the agents skill to get the complete definition:

   cd ${CLAUDE_PLUGIN_ROOT}/skills/agents
   ../../scripts/python.sh scripts/agent_get.py --ids <version_group_id>

3. Inspect the full definition - review system prompt, tools, model, capabilities
4. Only recommend/use if the actual definition is a strong fit for the task

Why: Agent names and brief descriptions in the types list can be misleading. The actual system prompt, tool configuration, and capabilities determine if an agent is suitable. Don't guess based on names alone.

Example - Correct vs Incorrect ID:

Tool metadata shows:
  ID: agents/0ad0ec8a-c49a-4784-9541-8c931aa0a365/...  ← DON'T USE
  Version group: 4ff1fc7a-2181-405d-a6d7-95b549eb7a10    ← USE THIS

# ❌ WRONG:
agent_get.py --ids 0ad0ec8a-c49a-4784-9541-8c931aa0a365
# Returns: "failed to retrieve agent"

# ✅ CORRECT:
agent_get.py --ids 4ff1fc7a-2181-405d-a6d7-95b549eb7a10
# Returns: Full agent definition

Script Reference

All scripts are nearly identical (just different paths):

Usage Examples

Query available models

../../scripts/python.sh scripts/models_search.py --limit 10
# Returns model IDs (UUIDs)
# NOTE: Filter only works by ID, not by name. Query all and filter client-side.

Query tools by name or description

# DEPRECATED: tools_search.py uses /queries endpoint which may be unstable
# Use tools_get.py instead for client-side filtering

../../scripts/python.sh scripts/tools_get.py --search "logscale query" --verbose
# Searches across name, description, and category
# Automatically filters out overly-broad terms like "falcon", "crowdstrike"
# Returns full tool entities with descriptions

# Legacy approach (may return 500 errors):
../../scripts/python.sh scripts/tools_search.py --filter 'name:"logscale"' --limit 20

Query tools by category

Use tools_get.py --category for an exact, case-sensitive category match. Prefer category filtering when the requested capability maps to one of the families below; add --search to narrow by name or description within that family.

../../scripts/python.sh scripts/tools_get.py \
  --category falcon_platform \
  --search "device query" \
  --limit 100

Category availability is tenant-specific. A zero-result category is not an error; report it and only broaden the search after explaining that exact category matching found nothing.

⚠️ IMPORTANT - Avoid Overly-Broad Search Terms:

• ❌ DON'T search for: "falcon", "crowdstrike", "cs" (too generic, matches everything)
• ✅ DO search for: specific capabilities like "host search", "detections", "vulnerability", "logscale query"
• Think: "What unique capability am I looking for?" not "What product is this in?"

Query agent templates

../../scripts/python.sh scripts/templates_search.py --filter 'category:"security"'

Query agent versions

../../scripts/python.sh scripts/versions_search.py \
  --filter 'agent_id:"<agent-id>"' \
  --limit 10

Query spans by trace ID

../../scripts/python.sh scripts/spans_search.py \
  --filter "trace_id:'abc123'+start_time:>='now-24h'" \
  --limit 100
# Note: Time filter required (start_time or end_time)
# Note: Use FQL syntax - operators are :>=, :<=, :<, :>, values in single quotes

Query spans by agent ID

../../scripts/python.sh scripts/spans_search.py \
  --filter "(attributes.aw_agent.id:'<agent-id>'+start_time:>='now-7d')+span_type:['aw_agent','aw_eval_run_started']" \
  --limit 500
# Note: FQL uses + for AND, , for OR
# Note: Wrap complex filters in parentheses
# Note: Filter by span_type for efficiency (agent-level spans only)

Hydrate span IDs to full entities

# First get span IDs from query (--json: the default output is a header plus an indented list)
SPAN_IDS=$(../../scripts/python.sh scripts/spans_search.py \
  --filter "trace_id:'abc123'+start_time:>='now-24h'" --json | jq -r '.resources[]')

# Then hydrate to full entities (SPAN_IDS is intentionally unquoted so each ID is its own argument)
../../scripts/python.sh scripts/spans_get.py --ids $SPAN_IDS
# Shows full span details: name, type, duration, status, credits, attributes

Common Pitfalls

Reading Guide

Allowed (all read-only):

• GET /agentic-studio/queries/models/v1
• GET /agentic-studio/queries/tools/v1
• GET /agentic-studio/queries/agent-templates/v1
• GET /agentic-studio/queries/agent-versions/v1
• GET /agentic-studio/queries/spans/v1 (requires time filter)
• GET /agentic-studio/entities/spans/v1 (hydrate span IDs)