clear precedence model. Global rules establish baseline conventions that apply across all projects. Workspace rules specialize or override global behavior for specific repositories. This hierarchy prevents configuration sprawl and ensures that framework-specific patterns don't leak into unrelated codebases.

Step 2: Implement Trigger-Based Routing

Never default to always-on triggers unless the instruction is universally applicable. Use glob patterns for language or framework-specific constraints, manual triggers for occasional workflows, and model-decision triggers for adaptive scenarios. Glob triggers are particularly efficient: the agent only loads the rule when file paths match, preserving context for active development.

Step 3: Structure Skills as Capability Modules

Skills should represent discrete capabilities, not general guidelines. Each skill lives in an isolated directory with a SKILL.md file. The frontmatter description acts as routing metadata: the agent evaluates this description against the current prompt to decide whether to load the skill. Precision in the description prevents unnecessary context inflation.

Step 4: Enforce Precedence Resolution

When global and workspace rules intersect, workspace rules must take precedence. This is handled natively by most agent runtimes, but you should explicitly document overrides to avoid ambiguity. Conflicting instructions cause the model to make arbitrary judgment calls, which degrades consistency.

Implementation Examples

Workspace Rule Configuration

---
trigger: glob
globs: "**/src/**/*.ts"
---

## TypeScript Architecture Standards
- Enforce strict type checking: `"strict": true` in `tsconfig.json`
- Prohibit implicit `any`; require explicit type definitions or `unknown` with type guards
- Prefer `const` declarations; `let` is restricted to loop counters and state mutations
- Use named exports exclusively; default exports are banned to improve refactoring safety
- Async operations must use `async/await`; raw `.then()` chains are prohibited
- Test files co-locate with source: `*.spec.ts` for unit tests, `__integration__/` for E2E
- Avoid synchronous blocking on the main thread; implement streaming or chunked processing for large datasets

Targeted Skill Module

---
name: api-contract-generation
description: Generate type-safe API contracts, request/response schemas, and client SDKs from OpenAPI specs. Use when the user requests endpoint definitions, data transfer objects, or automated client generation for REST or GraphQL services.
---

## Contract Generation Workflow
1. Parse the provided specification or requirements into a structured schema
2. Generate TypeScript interfaces for request payloads, response bodies, and error shapes
3. Implement Zod or Valibot validation schemas alongside type definitions
4. Produce a typed client wrapper with method signatures matching endpoint paths
5. Include error handling patterns and retry logic for network failures

## Design Constraints
- All generated types must be immutable (`readonly` properties)
- Validation schemas must mirror type definitions exactly; no manual drift
- Client methods should accept configuration objects for extensibility
- Include JSDoc comments with parameter descriptions and status code expectations
- Output must be framework-agnostic; avoid coupling to specific HTTP libraries

Architecture Rationale

• Glob triggers over always-on: Reduces context pollution. The agent only loads relevant rules when editing matching files, preserving tokens for active reasoning.
• Frontmatter descriptions as routing metadata: Enables deterministic skill invocation. The model evaluates the description against the prompt intent, loading only when necessary.
• Modular skill directories: Prevents monolithic configuration files. Each skill can be version-controlled, tested, and updated independently.
• Explicit precedence documentation: Eliminates ambiguity when global and workspace rules intersect. Teams can audit overrides without guessing model behavior.

Pitfall Guide

1. Context Saturation from Always-On Rules

Explanation: Activating every rule on every session floods the context window with irrelevant instructions. The model begins to ignore or compress directives, leading to inconsistent adherence. Fix: Reserve always-on triggers for universal conventions (e.g., language version, base linting rules). Use glob or manual triggers for framework-specific or situational constraints. Audit rule frequency quarterly.

2. Precedence Collisions Between Global and Workspace Rules

Explanation: When a global rule mandates one pattern and a workspace rule mandates another, the agent makes an arbitrary choice. This produces unpredictable outputs and breaks team conventions. Fix: Explicitly document override behavior. Use workspace rules to specialize, not contradict. Implement a naming convention like GLOBAL_ and WORKSPACE_ prefixes to clarify scope during audits.

3. Over-Engineering Skill Directives

Explanation: Skills that prescribe every implementation detail leave no room for contextual adaptation. The agent becomes rigid, failing to adjust to edge cases or novel requirements. Fix: Focus skills on principles, constraints, and output expectations rather than step-by-step recipes. Explain the rationale behind constraints so the model can apply judgment when edge cases arise.

4. Token Bloat in Skill Files

Explanation: Loading a 4,000-word skill file on every invocation consumes significant context and increases latency. Large files also dilute the agent's focus on the immediate task. Fix: Keep skills under 1,500 words. Extract reusable patterns into separate modules. Use concise, directive language. Remove theoretical explanations that don't directly impact output generation.

5. Literal Instruction Binding (Cargo-Culting)

Explanation: Agents often apply rules mechanically without understanding trade-offs. A directive like "always use named exports" may be applied in contexts where default exports improve readability or framework compatibility. Fix: Include brief rationale in rules. Example: "Prefer named exports because they enable safer refactoring and explicit dependency tracking." This encourages the model to reason about applicability rather than pattern-match blindly.

6. Neglecting Version Control for Agent Configurations

Explanation: Rules and skills stored locally without version control drift across team members. New hires inherit outdated conventions, and critical updates are lost. Fix: Commit all rule and skill files to the repository. Use a dedicated .agent/ or .windsurf/ directory. Implement CI checks to validate frontmatter syntax and trigger configurations before merging.

7. Ignoring Model-Specific Tokenization Limits

Explanation: Different models tokenize text differently. A rule file that fits comfortably in a 128K context window may exceed limits on models with aggressive tokenization or lower effective context budgets. Fix: Test rule and skill files against target models. Use token counters during development. Split large skills into sub-modules if approaching 80% of the model's context limit.

Production Bundle

Action Checklist

• Audit existing prompts: Identify repeated instructions and migrate them to global or workspace rules
• Define trigger strategy: Assign glob, manual, or model-decision triggers based on scope and frequency
• Structure skill directories: Create isolated folders with precise frontmatter descriptions for each capability
• Establish precedence documentation: Explicitly map how workspace rules override global conventions
• Implement version control: Commit all agent configurations to the repository with CI validation
• Test context budget: Verify that loaded rules and skills stay within 70% of the target model's context window
• Schedule quarterly reviews: Remove deprecated rules, merge overlapping skills, and update trigger patterns

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo developer, single framework	Global rules with glob triggers	Centralized, low maintenance, covers all projects	Minimal token overhead
Team project, strict conventions	Workspace rules + targeted skills	Enforces team standards, isolates framework patterns	Moderate setup time, high consistency ROI
Multi-framework monorepo	Workspace rules per package + shared global baseline	Prevents cross-framework contamination, allows specialization	Higher maintenance, prevents context pollution
High-latency environment	Manual triggers + lightweight skills	Reduces always-on context load, loads only when needed	Lower baseline latency, higher manual overhead
Rapid prototyping	Model-decision triggers + minimal global rules	Allows flexibility, reduces configuration friction	Higher output variance, faster iteration

Configuration Template

---
trigger: glob
globs: "**/src/**/*.ts"
---

## Project Standards
- Enforce strict type checking and explicit null handling
- Prefer immutable data structures; avoid direct mutation
- Use named exports; default exports require explicit justification
- Async operations must implement timeout and retry logic
- Tests co-locate with source; integration tests isolated in `__tests__/`
- Document public APIs with JSDoc including parameter types and return shapes

## Skill: Data Validation
---
name: data-validation-patterns
description: Generate runtime validation schemas, type guards, and error handling for external data sources. Use when processing API responses, user input, or configuration files.
---

## Validation Workflow
1. Define expected shape using TypeScript interfaces
2. Generate runtime validation schema (Zod/Valibot) matching type definitions
3. Implement type guards for conditional logic branches
4. Add error mapping to convert validation failures to domain-specific errors
5. Include logging for rejected payloads with sanitized error details

## Constraints
- Validation schemas must be generated, not manually maintained
- Type guards must return `value is T` for compiler narrowing
- Error objects must include path, expected type, and received value
- No silent failures; all validation errors must propagate to caller

Quick Start Guide

1. Create a .windsurf/ directory in your project root (or use your agent's settings UI)
2. Add a PROJECT_RULES.md file with glob triggers matching your primary language/framework
3. Create a skills/ directory and add a SKILL.md file for your most frequent workflow
4. Commit the directory to version control and verify trigger activation in a new agent session
5. Iterate: monitor context usage, adjust triggers, and split skills that exceed 1,500 words