| name | environment-design |
| description | Optimize the agent's working environment (project structure, config files, tool availability) to make productive actions obvious and error-prone patterns invisible. Use when setting up a project, auditing a codebase, or reducing friction in development workflows. |
You are an AI agent applying the Environment Design framework from Atomic Habits by James Clear to your operational workspace. Use this skill to engineer the project structure, configuration, and tooling so that the RIGHT actions are frictionless and the WRONG actions require deliberate effort.
Core Principle
"Motivation is overrated; environment often matters more." An agent doesn't need better prompting — it needs a better-structured workspace. When the project layout, configs, and tool integrations are optimized, productive behavior becomes the path of least resistance.
The Two Laws of Environment Design (Agent Version)
1st Law: Make It Obvious (Promote Good Patterns)
Surface critical information and tools so they are immediately accessible:
- Move important config files to the project root (not buried 3 levels deep)
- Create a
README.md with clear setup instructions so the agent finds context instantly
- Use descriptive file names and directory structures (not
[poorly_named_file])
- Place
.env.example alongside .env so required variables are obvious
- Add
CONTRIBUTING.md to surface coding conventions
2nd Law (Inversion): Make It Invisible (Suppress Bad Patterns)
Hide or gate dangerous operations so they require deliberate effort:
- Add
.gitignore to prevent committing secrets, build artifacts, and temp files
- Use
pre-commit hooks to block malformed commits automatically
- Configure [linter]/[formatter] to auto-reject anti-patterns before they enter the codebase
- Lock production branch with required reviews — making direct pushes impossible
- Remove dead code and unused dependencies to reduce cognitive noise
The Environment Audit
Step 1: Scan the Workspace
Using list_dir, find_by_name, and grep_search, audit the current project for:
- Exposed secrets (.env files, API keys in source)
- Missing documentation (no README, no setup guide)
- Clutter (temp files,
[dependency_folders] checked in, [compiled_binaries] scattered)
- Broken conventions (mixed naming styles, inconsistent folder structure)
Step 2: Apply Friction Engineering
- Promotion (reduce steps for good behavior): Add scripts to
[dependency_manifest] so running tests is [test_command], not a 3-step manual process.
- Reduction (increase steps for bad behavior): Add branch protection so deploying to production is a multi-step, reviewed process — not a single
git push.
Step 3: Create Context Separation
Each directory should have a single purpose:
/src for source code — not mixed with configs/tests for test files — not scattered across source directories/docs for documentation — not inline comments only/scripts for automation — not embedded in READMEs
Agent-Native Examples
| Friction Problem | Environment Fix | Effect |
|---|
| Agent can't find config | Move [config_file] to project root | Instant context |
| Tests require manual setup | Add [setup_script] | One-command testing |
| Secrets in source code | Add .gitignore + secret scanning | Prevent leaks |
| Inconsistent code style | Add [formatter_config] + pre-commit hook | Auto-enforcement |
| Unused imports everywhere | Configure auto-remove in linter | Clean codebase |
Anti-patterns to Watch For
- Relying on "agent discipline" instead of tooling enforcement
- Over-engineering the structure before writing any code
- Mixing concerns in directories (tests + source + configs in one folder)
- Not updating
.gitignore after adding new tools/frameworks
Output
When applying this skill, produce:
- An audit of current friction points in the workspace
- A list of "promotion" changes (make good patterns easier)
- A list of "reduction" changes (make bad patterns harder)
- The specific file/config changes to implement
