Knowledge Tree

🏄 Windsurf

3 min read

⚡ Bundle Cascade instructions, scripts, and templates for multi-step tasks.

📁 Layout & Scopes

  • Directory Structure:
    • Root: .windsurf/skills/skill-name/
    • SKILL.md: Required entry point
    • scripts/: Executable scripts
    • references/: Documentation/guides
    • assets/: Templates/configs/schemas
  • Scopes:
    • Workspace: .windsurf/skills/ (Current project only)
    • Global: ~/.codeium/windsurf/skills/ (All projects)

📝 SKILL.md Schema

  • Frontmatter Rules:
    • name: Required, 1-64 chars, lowercase, hyphens only, no double hyphens (—), no leading/trailing hyphens
    • description: Required, 1-1024 chars, include trigger keywords for auto-invoke
    • license: Optional, license name or file reference
    • compatibility: Optional, environment requirements
    • metadata: Optional, custom key-value pairs
    • allowed-tools: Optional, pre-approved tool list
  • Template: 
    ---
name: skill-name
description: What it does and when to invoke. Trigger keywords.
---

⚡ Usage & Creation

  • Invocation Methods:
    • Auto (Progressive Disclosure): Cascade reads descriptions (~100 tokens each) at startup. Loads full SKILL.md on match (<5000 tokens recommended).
    • Manual: Type @skill-name in Cascade input.
  • Best Practices:
    • Description: Use action keywords (deploy, review, test, generate, analyze). Specify when to use (e.g. Use when deploying…).
    • Token budget: Keep SKILL.md body <5000 tokens. Reference external files for large content.
  • Creation:
    • UI: Cascade panel -> three dots (⋮) -> Skills -> + Workspace or + Global -> name skill.
    • CLI: mkdir -p .windsurf/skills/my-skill && touch .windsurf/skills/my-skill/SKILL.md
  • Validation:
    • skillport: uv tool install skillport && skillport validate
    • skills-ref: npx skills-ref validate ./my-skill
  • Naming Conventions:
    • Allowed characters: 1-64 characters, lowercase, hyphens only
    • Constraints: No double hyphens (—), no starting or trailing hyphens
    • Valid examples: deploy-staging, code-review, run-tests
    • Invalid examples: Deploy-Staging, -deploy, deploy—staging

⚔️ Skills vs Rules vs Workflows

  • Comparison:
    • Skills:
      • Purpose: Complex tasks + resources
      • Structure: Directory with files
      • Trigger: @name or Auto
      • Ideal For: Build, review, test, deploy
    • Rules:
      • Purpose: Behavioral guidelines
      • Structure: Single .md
      • Trigger: Always-on / Glob
      • Ideal For: Style, conventions
    • Workflows:
      • Purpose: Repeatable sequences
      • Structure: Single .md
      • Trigger: /name
      • Ideal For: Build/test/deploy flows

🏗️ Templates & Examples

  • deploy-staging:
    • Layout: SKILL.md, scripts/pre-deploy-checks.sh, scripts/rollback.sh, references/deployment-guide.md, assets/environment-template.env
    • Steps: (1) Run tests & check uncommitted changes, (2) Run scripts/pre-deploy-checks.sh, (3) Build & deploy, (4) Run smoke tests, (5) Rollback: scripts/rollback.sh
  • code-review:
    • Layout: SKILL.md, references/style-guide.md, references/security-checklist.md, references/review-template.md, assets/pr-template.md
    • Steps: (1) Read PR description & linked issues, (2) Check style/security guide, (3) Verify tests & check for hardcoded secrets, (4) Comment/approve
  • run-tests:
    • Layout: SKILL.md, scripts/run-coverage.sh, references/testing-patterns.md, assets/test-template.py, assets/coverage-config.json
  • Quick Start Template: 
    ---
name: my-skill
description: [ACTION] [WHAT] [WHEN]. Use when [trigger keywords].
---
## Steps
1. Prerequisites
2. Steps
3. Troubleshooting/Rollback

🔗 Key Links

Generated: 2026-01-23 | Source: Windsurf Docs + Agent Skills Spec

Graph View

Backlinks