Skip to content

CLAUDE.md

Latest commit

 

History

History
188 lines (138 loc) · 10.5 KB

CLAUDE.md

File metadata and controls

188 lines (138 loc) · 10.5 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code when working with the foundry-skills plugin.

Plugin Overview

This plugin provides specialized Claude Code skills for systematic CrowdStrike Foundry development. Clone and configure:

git clone https://github.com/CrowdStrike/foundry-skills.git

Prerequisites

Foundry Development Skills Ecosystem

Overview

The skills/ directory contains specialized Claude Code 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 foundry-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 → foundry-ui-development
  • Data capabilities → foundry-collections-development
  • Logic capabilities → foundry-functions-development
  • Automation capabilities → foundry-workflows-development

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

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 Claude 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.

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:

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

Support Skills

Cross-cutting concerns and troubleshooting:

  • foundry-security-patterns: OAuth scoping, input validation, UI security
  • foundry-debugging-workflows: Systematic troubleshooting for CLI, manifest, and API issues

Skills Usage Patterns

Starting New Foundry Development

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

Working with Existing Foundry Apps

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

Common Development Scenarios

  • "Add UI extension" → foundry-ui-development skill
  • "Create data schema" → foundry-collections-development skill
  • "Build API endpoint" → foundry-functions-development skill
  • "Automate workflow" → foundry-workflows-development skill
  • "Call Falcon API from Function" → foundry-functions-falcon-api skill
  • "Expose external API to Foundry" → foundry-api-integrations skill
  • "Troubleshoot deployment" → foundry-debugging-workflows skill

Skills Integration with Claude Code Workflows

Planning Integration: For structured planning with review checkpoints, install superpowers (superpowers:writing-plans, superpowers:executing-plans). Without superpowers, the orchestrator provides basic planning guidance that accounts for Foundry's 47 capability types and manifest dependencies.

Execution Integration: If superpowers is installed, superpowers:executing-plans provides batch execution with review checkpoints between capabilities. Otherwise, use the orchestrator's built-in execution checkpoints.

Testing Integration: If superpowers is installed, superpowers:test-driven-development enforces RED-GREEN-REFACTOR discipline. Each Foundry sub-skill also has its own capability-specific testing patterns.

Handoff Integration: Preserve Foundry-specific CLI state (profiles, authentication, foundry ui run status) when handing off between sessions.

Counter-Rationalizations

The skills enforce discipline to prevent common failures:

Your Excuse Reality
"I have API experience" Foundry APIs have platform-specific auth, discovery, and error handling
"Time pressure means skip sub-skills" Sub-skills PREVENT rework that costs 10x more time
"I can learn patterns during implementation" Learning while implementing = building on wrong assumptions
"Sub-skills are overkill for simple cases" No Foundry capability is simple - platform complexity is hidden

Essential Skills Commands

Accessing Skills: Skills are automatically invoked by Claude Code when working on Foundry development tasks. You can reference them explicitly using @skills/skill-name syntax.

Skills Documentation: Each skill includes comprehensive documentation in its SKILL.md file with specific patterns, testing approaches, and integration guidance.

Skills Coordination: The foundry-development-workflow skill ensures proper coordination between all sub-skills and maintains CLI state consistency throughout development.

Automated Safety Enforcement: The plugin includes a PreToolUse hook (foundry-cli-guard.sh) that automatically validates all Bash commands to ensure:

  • Foundry CLI commands always include --no-prompt flag (prevents Error: EOF failures)
  • Manual directory/file creation for app structure is blocked (prevents invalid manifest.yml)
  • Commands are corrected before execution with clear error messages

This enforcement runs automatically - you don't need to remember the rules, the hook will catch mistakes before they cause failures.

Essential Foundry CLI Commands

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

Claude Code operates in a non-interactive environment. 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                       # View available profiles (US-1, US-2, EU-1, US-GOV)
foundry profile active                     # Show current active profile
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 deploy --change-type Patch --change-log "msg" --no-prompt  # Deploy to cloud
foundry apps release --change-type Patch --deployment-id <id> --notes "notes"  # Release to app catalog
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 navigation add --name "X" --path / --ref pages.xxx  # 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 workflows create --name "X" --spec path.yaml --no-prompt            # Create workflow

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 (deploy early after API integrations and collections to catch spec issues)
  • 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