Agent development rules for AI coding assistants.
Drop these into your project — your AI assistant will understand OpenClaw conventions,
SOUL.md structure, agent architecture, and deployment patterns.

---

Quick Start

One-line install (auto-detects your editor):

curl -fsSL https://raw.githubusercontent.com/mergisi/openclaw-rules/main/install.sh | bash

Manual install

# Claude Code
git clone --depth 1 https://github.com/mergisi/openclaw-rules.git .rules-tmp
mkdir -p .claude/rules && cp .rules-tmp/project-rules/*.mdc .claude/rules/
rm -rf .rules-tmp

# Cursor
mkdir -p .cursor/rules && cp .rules-tmp/project-rules/*.mdc .cursor/rules/

# Windsurf
mkdir -p .windsurf/rules && cp .rules-tmp/project-rules/*.mdc .windsurf/rules/

---

Supported Editors

Editor	Rules Directory	Status
Claude Code	.claude/rules/	Fully supported
Cursor	.cursor/rules/	Fully supported
Windsurf	.windsurf/rules/	Fully supported
Any LLM	Paste into system prompt	Works everywhere

---

Rules

Project Rules

Rules that apply per-project. Drop into your agent's repo.

#	Rule	What it teaches your AI
1	soul-md-guide.mdc	How to write effective SOUL.md identity files
2	agent-architecture.mdc	Directory structure, config.json, naming conventions
3	heartbeat-config.mdc	Cron scheduling, intervals, offset patterns
4	tool-scripts.mdc	Zero-dep Node.js scripts (GA4, Stripe, Reddit, etc.)
5	telegram-bot.mdc	Telegram bot integration, message formatting
6	deploy.mdc	Deploy to Mac, Raspberry Pi, VPS, Docker
7	multi-agent.mdc	Team patterns: Reporter, Scout-Writer, Monitor-Alert
8	memory-system.mdc	MEMORY.md, USER.md, context loading order

Global Rules

Rules that apply across all your projects.

#	Rule	What it teaches your AI
9	openclaw-conventions.mdc	General coding conventions for OpenClaw projects

---

Examples

Ready-to-use agent setups you can copy into your project:

Minimal Agent

3 files — the smallest working agent.

examples/minimal-agent/
├── SOUL.md        # Agent identity and rules
├── config.json    # Metadata and capabilities
└── MEMORY.md      # Persistent memory template

Metrics Agent

Business intelligence agent with GA4 + Stripe tools.

examples/metrics-agent/
├── SOUL.md        # Data-driven analyst personality
└── config.json    # GA4, Stripe, Mixpanel capabilities

---

Rule Format

Rules use .mdc (Markdown with Context) — plain markdown that AI coding assistants parse natively:

# Rule Title

Description of when and how to apply this rule.

## Key Points
- Convention or pattern
- Do this, not that

## Examples
code examples, templates, patterns

No special tooling needed. It's just markdown.

---

Why?

Every time you start a new agent project, your AI assistant asks the same questions:

• "What's a SOUL.md?"
• "How should I structure the config?"
• "How do heartbeats work?"
• "How do I write a tool script?"

These rules answer those questions before they're asked. Your AI assistant reads the rules and writes correct OpenClaw code from the start.

Before:  "Can you explain what SOUL.md is?" → explain → fix → explain again
After:   AI already knows. Just builds.

---

Contributing

PRs welcome. If you've found a pattern that makes agent development better, add a rule.

1. Fork the repo
2. Add your rule to project-rules/ or global-rules/
3. Follow the .mdc format above
4. Open a PR

---

Related Projects

Project	Description
awesome-openclaw-agents	53 ready-to-use agent templates
CrewClaw	Generate and deploy OpenClaw agents in 5 minutes
OpenClaw Docs	Official documentation

---

_{MIT License © 2026 Mustafa Ergisi}