---
slug: "agent-rules"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/dtsvetkov1/agent-rules@main/README.md"
repo: "https://github.com/dtsvetkov1/agent-rules"
source_file: "README.md"
branch: "main"
---
# React Native Expo AI Agent Rules

An opinionated set of AI coding guidelines and commands for React Native Expo projects. These rules help AI assistants (like Cursor, Claude, ChatGPT) generate consistent, high-quality code following best practices.

## Quick Start

### Automated Installation

Run this one-liner in your React Native Expo project root:

```bash
curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh | bash
```

Or download and run the script manually:

```bash
curl -fsSL https://raw.githubusercontent.com/dtsvetkov1/agent-rules/main/setup.sh -o setup.sh
chmod +x setup.sh
./setup.sh
```

### Manual Installation

If you prefer to install manually, just download the needed files from the repository and put them in your project

## What Gets Installed

After installation, your project will have:

```
your-project/
├── AGENTS.md                           # Main AI coding guidelines (https://agents.md/)
├── .cursor/
│   ├── rules/
│   │   └── react-native-expo-guidelines.mdc  # Cursor-specific rules
│   ├── commands/                       # Command templates for common workflows (https://cursor.com/docs/agent/chat/commands)
│   │   ├── code-review-checklist.md    # Review checklist
│   │   ├── ...
│   ├── hooks.json                      # Hook configuration
│   └── hooks/                          # Hook scripts that run automatically after certain actions (https://cursor.com/docs/agent/hooks)
│       ├── audit.sh                    # Audit agent actions
│       ├── ...
```

## What's Inside

### Core Guidelines (AGENTS.md)

Comprehensive guidelines covering:

- **Tech Stack**: Bun, TypeScript, Expo Router, Zustand, Reanimated
- **Project Structure**: Directory organization and naming conventions
- **Component Patterns**: Best practices for React Native components
- **State Management**: Zustand patterns and store organization
- **Animations**: React Native Reanimated guidelines
- **Performance**: Optimization techniques and best practices
- **Security**: Secure coding practices and data protection
- **Testing**: Unit, integration, and E2E testing strategies

### Quick Reference

#### Must-Use Technologies

- Bun (package manager)
- TypeScript (all files)
- Expo Router (navigation)
- Zustand (state management)
- React Native Reanimated (animations)
- expo/fetch (HTTP requests)
- Uniwind (styling)

### Command Templates

Pre-built workflows for common tasks:

- **setup-new-feature**: Systematic feature development
- **code-review-checklist**: Ensure code quality before PR
- **security-audit**: Security best practices validation
- **build-deploy**: Build and deployment workflows
- **run-tests-fix-failures**: Testing and debugging
- **code-quality**: Code quality analysis
- **update-documentation**: Documentation maintenance

### Cursor Hooks

AI agent lifecycle hooks for safety and quality:

- **format.sh**: Auto-formats edited files with Prettier/ESLint
- **audit.sh**: Logs all agent actions to `~/.cursor/audit/agent-audit.log`
- **block-dangerous-git.sh**: Prevents force pushes to main/master and other risky git operations
- **check-secrets.sh**: Scans prompts for API keys, tokens, and secrets before submission

Hooks run automatically and require a Cursor restart after installation. Check the Hooks tab in Cursor Settings to debug.

### Agent Skills

Agent skills are specialized instruction sets that provide the AI with deep knowledge and specific procedures for complex tasks. Think of them as "plugins" for your AI agent's brain that ensure expert-level handling of specific domains.

**How to apply them:**
Simply ask the agent to use a specific skill (e.g., "Use the mobile-perf skill to analyze this component") or let the agent autonomously select the relevant skill based on your task.

**Example skills included in `skills/`:**
- **api-expert**: Standards for API route implementation and data fetching
- **change-writer**: Structured format for generating changelogs and commit messages
- **mobile-perf**: React Native performance profiling and optimization techniques
- **navigation-architect**: Deep knowledge of Expo Router and navigation patterns
- **security-audit**: Comprehensive security checklist for mobile apps

#### Recommended Skills

We recommend enhancing your agent with these external skill sets:

- **React Native Skills**: [callstackincubator/agent-skills](https://github.com/callstackincubator/agent-skills) - Specialized skills for React Native development
- **React Skills**: [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills/) - Vercel's engineering best practices
- **Architecture Decision Records**: [ADR Skill](https://github.com/wshobson/agents/blob/main/plugins/documentation-generation/skills/architecture-decision-records/SKILL.md) - For documenting architectural choices
- **Agent Memory**: [Agent Memory](https://github.com/yamadashy/repomix/blob/main/.claude/skills/agent-memory/SKILL.md) - Techniques for maintaining long-term context

### Installation

You can install skills at the **Project Level** or **System Level** (bigger-picture rules).

#### 1. Project Level (Recommended)
This makes the skills available to everyone working on the project and ensures consistent behavior across the team.

-   **Location:** `.claude/skills/`, `.cursor/skills/` or `.opencode/skills/` 
-   **Purpose:** Skills specific to the project's tech stack (e.g., `api-expert`, `navigation-architect`) or shared team workflows.
-   **Setup:**
    ```bash
    mkdir skills
    # Copy specific skills
    cp -r path/to/agent-rules/skills/mobile-perf ./skills/
    ```

#### 2. System Level
Use this for generic skills you want to use across multiple projects without cluttering each repository.

-   **Location:** A central directory like `~/.cursor/skills/`,  `~/.claude/skills/` or  `~/.config/opencode/skills/` 
-   **Purpose:** Generic tools you use everywhere
-   **Setup:**
    1.  Create a central folder (if not exists)
    2.  Clone or copy skills there.

### Configuration by Tool

-   **Cursor**:
    -   **Project Level:** Cursor will index the `./skills/` folder automatically.
    -   **System Level:** Add the folder to your "Codebase" in settings or reference files using `@` (default  `~/.cursor/skills/`).
    -   **Tip:** Add a rule in `.cursor/rules` explicitly telling the agent: *"Always check `./skills/` for relevant capabilities before starting a task."*
-   **Claude Code**:
    -   **Project Level:** Ensure the `.claude/skills/` directory is included in your context.
    -   **System Level:** You must pass the skill file path argument when running Claude or add it to the context manually.
    -   **Config:** make sure `skills/` is **not** ignored.
-   **OpenCode**:
    -   **Project Level:** OpenCode agents automatically scan the project root for a `skills/` directory and parse `SKILL.md` files.
    -   **System Level:** Configuration depends on the specific OpenCode runtime environment.

## Usage

### With Cursor AI

1. Install the rules using the setup script
2. Open your project in Cursor
3. Start coding - the AI will automatically follow `react-native-expo-guidelines.mdc` rules (its configured to always apply, feel free to change it if needed)
4. Use command templates from `.cursor/commands/` for common workflows with `/` prefix, like `/run-tests-fix-failures` for running tests and fixing failures, or `/update-documentation` for updating documentation

### With Other AI Assistants

1. Share the `AGENTS.md` file with your AI assistant (Claude, ChatGPT, Cursor, etc.)
2. Reference specific sections when asking for code generation
3. Use the guidelines as a reference for code reviews (if needed)

## Customization

After installation, feel free to customize the rules for your specific project:

1. Edit `AGENTS.md` to match your project structure or specific needs
2. Update `.cursor/rules/` for Cursor-specific preferences
3. Modify command templates in `.cursor/commands/`
4. Commit changes to your repository if needed

---

Created for React Native Expo projects to ensure consistent, high-quality AI-assisted development.

## TODO/improvements

- dont duplicate agent md for cursor?
- less comments, start from small letter
- mcp servers config
- add option to download only certain files or directories
- add additional configs for claude code (subagents, hooks, output styles etc)