AI Agent Instructions for foundry-skills

This repository is an AI coding assistant plugin for CrowdStrike Falcon Foundry development. It provides specialized skills that guide AI assistants through building complete Foundry apps, covering UI pages, serverless functions, data collections, automation workflows, and API integrations.

The skills are markdown-based and usable by any AI coding assistant. Claude Code users should also see CLAUDE.md for plugin-specific hook and integration details.

Prerequisites

• Foundry CLI: Install cross-platform:
  • macOS/Linux: brew tap crowdstrike/foundry-cli && brew install crowdstrike/foundry-cli/foundry
  • Windows: Download https://assets.foundry.crowdstrike.com/cli/latest/foundry_Windows_x86_64.zip, expand it, add the installation directory to PATH
• Authentication: Run foundry login to authenticate with CrowdStrike, or use foundry profile create --no-prompt for headless environments
• Development Environment: Node.js, Python, or Go depending on your app requirements
• CLI Reference: https://docs.crowdstrike.com/r/v5114866

Repository Structure

• skills/ - 13 skills, each with a SKILL.md file
• hooks/ - Plugin hook scripts for intent routing and safety enforcement
• use-cases/ - Real-world implementation patterns extracted from CrowdStrike Tech Hub blog posts
• skills/*/scripts/ - Skill-specific helper scripts (OpenAPI adaptation, action search, Fusion redirect detection, deploy and release)
• .claude-plugin/ - Claude Code plugin manifest and marketplace configuration

Skills Ecosystem

The skills/ directory contains specialized skills that provide systematic approaches for Foundry development. These skills enforce best practices, prevent technical debt, and ensure platform-specific patterns are followed correctly.

Core Principles

Mandatory Sub-Skill Delegation: The development-workflow skill enforces that all capability development must use the appropriate specialized sub-skill. This prevents platform-specific mistakes and ensures consistent quality.

Capability-Based Architecture: Each skill maps to specific Foundry platform capabilities:

• UI capabilities → ui-development
• Data capabilities → collections-development
• Logic capabilities → functions-development
• Automation capabilities → workflows-development
• AI capabilities → ai-agents-development

Security-First Design: Security patterns are integrated throughout all skills, with dedicated security-patterns for specialized security guidance.

Primary Workflow Skills

Foundry Development Workflow (Primary Orchestrator)

Always starts here - coordinates complete app lifecycle and enforces sub-skill delegation.

Critical Functions:

• CLI state management (foundry profile, authentication, foundry ui run)
• Manifest.yml coordination across all capabilities
• Sub-skill delegation enforcement (NO direct implementation allowed)

Capability-Specific Skills

Specialized skills for each Foundry capability type:

• ui-development: Vue/React + Shoelace UI components and extensions
• collections-development: JSON Schema data modeling and CRUD operations
• functions-development: Go/Python serverless functions with CrowdStrike SDK
• workflows-development: YAML automation workflows and Fusion orchestration
• functions-falcon-api: Calling Falcon APIs from within Functions (OAuth, SDKs)
• api-integrations: Exposing external APIs via OpenAPI specs
• ai-agents-development: AI agents and knowledge bases, plus exposing collections and API operations as agent tools

Support Skills

Cross-cutting concerns and troubleshooting:

• security-patterns: OAuth scoping, input validation, UI security
• debugging-workflows: Systematic troubleshooting for CLI, manifest, and API issues
• e2e-testing: End-to-end testing with @crowdstrike/foundry-playwright
• app-upgrades: Upgrade a template-installed app to a newer template version, keeping its IDs
• app-audit: Scan an existing app for documented anti-patterns, with --fix for the safe ones
• fusion-redirect: Points a standalone Falcon Fusion workflow request (no Falcon Foundry app needed) to the Falcon Fusion plugin

Use Cases

The use-cases/ directory contains real-world implementation patterns extracted from CrowdStrike Tech Hub blog posts. Each file captures an actionable pattern (not a summary) that AI assistants can apply when users describe similar scenarios. The orchestrator searches use-case frontmatter to match user requests, and sub-skills reference specific use cases for context.

Skills Usage Patterns

Starting New Foundry Development

1. development-workflow coordinates the lifecycle
2. Specialized sub-skills for each capability (UI, Collections, Functions, Workflows)
3. security-patterns for security review

Working with Existing Foundry Apps

1. development-workflow assesses current state
2. Appropriate sub-skill for the capability being modified
3. debugging-workflows if issues arise
4. security-patterns for security validation

Common Development Scenarios

• "Add UI extension" → ui-development skill
• "Create data schema" → collections-development skill
• "Build API endpoint" → functions-development skill
• "Automate workflow" → workflows-development skill
• "Call Falcon API from Function" → functions-falcon-api skill
• "Expose external API to Foundry" → api-integrations skill
• "Create an AI agent" → ai-agents-development skill
• "Add a knowledge base" → ai-agents-development skill
• "Troubleshoot deployment" → debugging-workflows skill
• "Add e2e tests" → e2e-testing skill
• "Upgrade an app installed from a template" → app-upgrades skill
• "Audit my app" / "check it for anti-patterns" → app-audit skill

Essential Foundry CLI Commands

⚠️ CRITICAL: Always use --no-prompt with creation commands

AI coding assistants operate in non-interactive environments. Commands that prompt for user input will fail with Error: EOF. ALWAYS include --no-prompt on any command that supports it.

🚫 NEVER CREATE APP DIRECTORIES OR FILES MANUALLY

ABSOLUTELY FORBIDDEN: Using mkdir, touch, or manually creating app-related directories (api-integrations/, workflows/, functions/, collections/, ui/) or files (manifest.yml, etc.). The Foundry CLI generates these with correct structure, IDs, and manifest entries.

If a CLI command fails:

1. ✅ Fix the command (add --no-prompt, check flags, verify auth)
2. ✅ Retry the corrected CLI command
3. ❌ NEVER fall back to mkdir or manual creation

Manual creation causes: Invalid manifest.yml, missing generated IDs, broken app structure, hours of debugging

# Authentication & Environment Management
foundry login                              # OAuth-based authentication
foundry profile list                       # Lists profiles; the first line shows the active one
foundry profile activate --name <name>     # Switch between environments

# App Development Lifecycle
foundry apps create --name "X" --no-prompt --no-git  # Create new app
foundry apps run                           # Start full app locally in dev mode
foundry apps validate --no-prompt           # Dry-run validation (no deploy)
foundry apps deploy --change-type Patch --change-log "msg" --no-prompt  # Deploy to cloud
foundry apps release --change-type Patch --deployment-id <id> --notes "Release notes" --no-prompt  # Release to app catalog (notes: 10-1000 chars)
foundry ui run                             # Local UI development server

# Scaffolding Commands (ALWAYS use --no-prompt)
foundry api-integrations create --name "X" --spec path.json --no-prompt   # Create API integration
foundry ui pages create --name "X" --from-template React --no-prompt       # Create UI page
foundry ui extensions create --name "X" --from-template React --sockets "socket.name" --no-prompt  # Create UI extension
foundry ui extensions list-sockets                                                                # List available socket IDs
foundry ui navigation add --name "X" --path / --ref pages.xxx --no-prompt  # Add navigation
foundry functions create --name "X" --language python --no-prompt           # Create function
foundry collections create --name "X" --schema path.json --no-prompt        # Create collection
foundry collections create --name "X" --schema path.json --agent-tools-expose --no-prompt  # ...exposed as an agent tool
foundry workflows create --name "X" --spec path.yaml --no-prompt            # Create workflow
foundry knowledge-bases create --name "X" --files a.md,b.csv --no-prompt     # Create knowledge base (--files required)
foundry agents create --name "X" --system-prompt path.md --knowledge-bases "X" --no-prompt  # Create AI agent (KB must exist first)
foundry agents delete --name "X" --no-prompt                                # Delete AI agent
foundry knowledge-bases delete --name "X" --no-prompt                       # Delete knowledge base

AI agents and knowledge bases: subcommands are create and delete only — there is no list or edit. Build knowledge bases before the agents that reference them; agents create validates the references and fails otherwise. Agent exposure is set at create time with --expose-charlotte-chat, --expose-agent-as-tool (requires --input-schema), and --expose-workflow-system-action; only model and tools lack CLI flags. Hand-edit manifest.yml only for those, for auth.scopes names that foundry auth scopes add rejects, to rename a deployed knowledge base, and to add or remove RBAC permission keys in an artifact's permissions: list (see security-patterns). See the ai-agents-development skill.

Quality and Thoroughness

When building Falcon Foundry apps, take your time and do each step thoroughly. Quality is more important than speed. Specifically:

• Do not skip validation steps (validate early after API integrations and collections with foundry apps validate --no-prompt)
• Do not skip the Vite noAttr() fix for UI pages - a blank page wastes more time than the 30 seconds to add it
• Read each sub-skill's Common Pitfalls section before implementing that capability
• Verify CLI commands succeed before moving to the next step - do not chain multiple scaffolding commands blindly

Security Considerations

• Never commit credentials - CLI handles authentication
• Scoped permissions - Request minimal required permissions in manifest
• Iframe security - UI runs in sandboxed environment
• API rate limiting - Respect CrowdStrike API limits

Contribution Conventions

• All SKILL.md versions must match the version in .claude-plugin/plugin.json
• Hook scripts in hooks/ must be executable (chmod +x)
• Run ./test-hooks.sh before submitting a pull request
• Run npx markdownlint-cli2 "**/*.md" to validate markdown formatting
• Snapshots and use-case files follow standardized frontmatter formats

Testing a branch in Codex

See the "Install from a local clone" section in the README. Codex always caches on install rather than loading live from disk, so changes require a remove + re-add cycle. ./test-assistants.sh handles isolation for you and restores your setup afterward.