Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aws-samples/sample-well-architected-skills-and-steering/llms.txt

Use this file to discover all available pages before exploring further.

Windsurf integrates Well-Architected guidance through a single .windsurfrules file — Windsurf’s native mechanism for persistent agent instructions. The file establishes your AI assistant as an AWS Well-Architected advisor, applies all six pillars to every architecture conversation, and routes structured assessment requests to the appropriate skill playbook in the skills/ directory.

​
What gets installed

.windsurfrules    ← always-on WA steering and skill routing
The .windsurfrules file contains:
  • Role definition — sets the agent as an AWS Well-Architected advisor
  • Six-pillar definitions — Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, and Sustainability
  • Design principles — managed services preference, failure design, least-privilege access, IaC, observability
  • Trade-off guidance — explicit acknowledgement of security/latency, cost/availability, and portability trade-offs
  • Skill routing — references the skills/ directory so Windsurf can follow step-by-step playbooks on demand

​
Installation

1

Copy .windsurfrules into your project root

cp path/to/this-repo/adapters/windsurf/.windsurfrules ./.windsurfrules
Or use the install script from a local clone:
./install.sh ~/my-project --tool windsurf
2

Verify the file is in place

Confirm .windsurfrules exists at the root of your project:
ls -la .windsurfrules
3

Test the integration

Open a Windsurf conversation in your project directory and ask a design question. The agent should apply WA principles and reference specific pillars.
What Well-Architected pillars should I consider for this architecture?

​
Usage

Windsurf reads .windsurfrules at the start of every session, so WA principles are active immediately. For structured deep-dive assessments, ask Windsurf to follow the relevant skill playbook: 
Run a Well-Architected review of this codebase.
To get the full structured playbook experience, copy the skills/ directory alongside .windsurfrules. The skill routing in .windsurfrules references skills/{skill-name}/SKILL.md, so Windsurf can read and follow the step-by-step instructions when asked.
cp path/to/this-repo/adapters/windsurf/.windsurfrules ./.windsurfrules
cp -r path/to/this-repo/skills ./skills
Windsurf’s .windsurfrules applies to all conversations in the workspace. If you only want WA guidance for specific projects, use a project-level install (the default). For guidance across all Windsurf projects, place .windsurfrules in your home directory.

Build docs developers (and LLMs) love

Get started for freeTalk to us