---
name: ai-agent-rules-creation
description: "Expert framework for creating, structuring, and maintaining AI agent rules, workflows, and persistent memory across different platforms (Gemini CLI, Cursor, Claude Code, etc.)."
tags: ["rules", "workflow", "agentic-design", "context-management"]
---

# AI Agent Rules Creation Skill

Use this skill when you need to define how an AI agent should behave, the processes it should follow, or how it should remember information. This skill transforms vague instructions into surgical, platform-aware mandates.

## 1. Core Concepts

### Rules (The "Laws")
Passive, persistent constraints that define the behavioral boundaries and quality standards.
- **Goal:** Consistency and safety.
- **Example:** "Never commit code without explicit user approval."

### Workflows (The "SOPs")
Active, structured sequences of steps or decision loops for solving complex problems.
- **Goal:** Repeatability and transparency.
- **Example:** "Research -> Strategy -> Execution -> Validation" cycle.

### Memory (The "Journal")
Dynamic accumulation of session-based knowledge and architecture decisions.
- **Goal:** Persistent state across multiple sessions.
- **Example:** "We chose Postgres because of X."

---

## 2. Platform-Specific Implementation

### Gemini CLI (`GEMINI.md`)
- **Structure:** Hierarchical (Global `~/.gemini/GEMINI.md` -> Project Root -> Subdirectory).
- **Mandate:** Use `/init` to generate a base. Use `/memory refresh` to hot-reload changes.
- **Tip:** Concatenate rules; later rules refine/override earlier ones.

### Claude Code (`CLAUDE.md`)
- **Structure:** Single root file for commands and style guides.
- **Memory:** Use `MEMORY.md` for auto-learning notes (first 200 lines are injected).
- **Mandate:** Keep files under 150 lines to prevent context dilution.

### Cursor (`.cursorrules` & `.mdc`)
- **Modern Pattern:** Use `.cursor/rules/*.mdc` (Markdown with Context).
- **Activation:** Use YAML frontmatter with `globs` (e.g., `globs: src/**/*.ts`) and `alwaysApply: false`.
- **Mandate:** Modularize rules to save tokens and improve relevance.

### GitHub Copilot (`.github/copilot-instructions.md`)
- **Structure:** Repository-wide (`.github/copilot-instructions.md`) and path-specific (`.github/instructions/*.instructions.md`).
- **Activation:** Automatically detected by Copilot Chat in VS Code and CLI.

---

## 3. Implementation Workflow

### Step 1: Research (The Map)
- Identify the target platform and its specific rule-file naming convention.
- Analyze existing project standards (tech stack, linting, testing).

### Step 2: Planning (The Blueprint)
- Decide between a **Global Rule** (all projects) or a **Local Rule** (specific project/folder).
- Categorize instructions into:
  - **Directives:** Unambiguous actions.
  - **Constraints:** Things NEVER to do.
  - **Context:** Project-specific tech debt or architectural choices.

### Step 3: Execution (The Build)
- Write rules using **Negative Constraints** (e.g., "DO NOT use class components") for better AI compliance.
- Use **XML-style tagging** (e.g., `<RULES>`, `<WORKFLOW>`) for structured parsing by advanced models.
- Include a **Validation Checklist** for the agent to follow.

### Step 4: Validation (The Test)
- Run a small task to see if the agent follows the new rules.
- Check the concatenated context (e.g., `/memory show` in Gemini CLI) to ensure no conflicts.

---

## 4. Best Practices Checklist
- [ ] Is the primary rule file under 150 lines?
- [ ] Are tech stacks explicitly defined (e.g., "Use FastAPI, not Flask")?
- [ ] Does every bug-fix rule require a reproduction test case?
- [ ] Is sensitive info (secrets) kept in `.env` and NOT in the rule files?
- [ ] Are workflows decomposed into "Micro-Agent" steps (Plan -> Act -> Validate)?
