creating-windsurf-packages

Windsurf rules must be plain markdown in a single .windsurf/rules file with a hard 12,000 character budget. Structure your guidelines using markdown sections and code blocks, avoiding frontmatter entirely, to stay within the constraint while keeping content organized and readable.

Windsurf rule packages use only plain markdown with no frontmatter. All rules reside in one .windsurf/rules file. You can organize content with sections and code blocks, but must respect the 12,000 character ceiling for the entire file.

No. Windsurf rules files reject frontmatter entirely. Use plain markdown formatting only, organizing your development guidelines through markdown headers, lists, and code blocks within the single-file, character-limited format.

Create a .windsurf/rules markdown file in your project root. Use markdown sections to organize guidelines by topic, insert code examples in fenced blocks, and optimize word choice to fit the 12,000 character budget while covering your project's standards.

Windsurf enforces a hard 12,000 character limit on the rules file. Content beyond this threshold is truncated or rejected. Prioritize essential guidelines and use concise language to communicate standards effectively within the constraint.