npm package: @mallardbay/cursor-rules
Description: Mallard Bay shared cursor rules
Author: mfrr1118
Latest version: 1.0.33

# Cursor Rules

A tool for managing Cursor IDE rules and Claude Code configuration across different environment types with shared base configurations.

## Overview

This project provides a structured way to manage AI agent rules and skills for different development environments while maintaining a shared base configuration. It generates:

- **Cursor IDE**: `.cursor/rules/*.mdc` files and `.cursor/skills/*/SKILL.md` files
- **Claude Code**: A combined `CLAUDE.md` file and `.claude/skills/*/SKILL.md` files
- **Codex**: A combined `AGENTS.md` file and `.codex/skills/*/SKILL.md` files
- **Cross-platform Skills**: Skills are automatically copied to all three platform directories for maximum compatibility

It supports three main environment types:

-   `frontend`: Basic frontend development rules
-   `frontend-lib`: Extended rules for frontend library development, inheriting from frontend rules
-   `backend`: Backend development rules

## Installation

```bash
npm install @mallardbay/cursor-rules
```

## Usage

To set up Cursor rules for your project, run:

```bash
npx @mallardbay/cursor-rules <env-type>
```

Where `<env-type>` can be either:

-   `frontend`
-   `frontend-lib`
-   `backend`

### Example

```bash
# For frontend development
npx @mallardbay/cursor-rules frontend

# For frontend library development
npx @mallardbay/cursor-rules frontend-lib

# For backend development
npx @mallardbay/cursor-rules backend
```

## Project Structure

The rules and skills are organized in the following directory structure:

```
.cursor/
├── shared/
│   ├── rules/     # Shared base rules
│   └── skills/    # Shared skills (installable workflows)
├── frontend/
│   └── rules/     # Frontend-specific rules
├── frontend-lib/
│   └── rules/     # Frontend library-specific rules
└── backend/
    └── rules/     # Backend-specific rules
```

## Rule Inheritance

The rules follow an inheritance pattern:

-   All environments include the shared base rules
-   `frontend-lib` inherits rules from both `frontend` and `frontend-lib` directories

## Output

Running the setup script generates:

```
your-project/
├── .cursor/
│   ├── rules/          # Cursor IDE rules (*.mdc files)
│   │   ├── code-quality.mdc
│   │   ├── testing.mdc
│   │   └── ...
│   └── skills/         # Cursor Skills (installable workflows)
│       ├── prep-for-pr/
│       │   └── SKILL.md
│       ├── review-pr/
│       │   └── SKILL.md
│       └── address-pr-feedback/
│           └── SKILL.md
├── .claude/
│   └── skills/         # Claude Code Skills (same skills)
│       ├── prep-for-pr/
│       │   └── SKILL.md
│       ├── review-pr/
│       │   └── SKILL.md
│       └── address-pr-feedback/
│           └── SKILL.md
├── .codex/
│   └── skills/         # Codex Skills (same skills)
│       ├── prep-for-pr/
│       │   └── SKILL.md
│       ├── review-pr/
│       │   └── SKILL.md
│       └── address-pr-feedback/
│           └── SKILL.md
├── CLAUDE.md           # Claude Code configuration (combined rules)
└── AGENTS.md           # Codex IDE configuration (combined rules)
```

Both `CLAUDE.md` and `AGENTS.md` combine all applicable rules into single files, with YAML frontmatter stripped for compatibility. Each file opens with a header comment that states the file is **auto-generated** (do not edit by hand) and that **project-specific rules** belong in `AGENTS_LOCAL.md`, plus which tool consumes the file.

Skills are automatically discovered by Cursor, Claude Code, and Codex, and can be invoked with `/skill-name` in chat. The setup script copies skills to all three platform directories for cross-platform compatibility.

### Project-Local Rules (`AGENTS_LOCAL.md`)

If your project needs additional rules beyond what the shared configuration provides, create an `AGENTS_LOCAL.md` file in your project root. Its content will be automatically appended to both `CLAUDE.md` and `AGENTS.md` when the setup script runs.

This is useful for:
- Project-specific conventions or architectural decisions
- Team-level overrides or additions
- Context that only applies to a single repository

```
your-project/
├── AGENTS_LOCAL.md    # Your project-specific rules (checked into version control)
├── CLAUDE.md          # Generated (includes AGENTS_LOCAL.md content)
└── AGENTS.md          # Generated (includes AGENTS_LOCAL.md content)
```

`AGENTS_LOCAL.md` is meant to be checked into version control, while `CLAUDE.md` and `AGENTS.md` are generated and should be gitignored.

## Development

### Adding New Rules

1. Create `.mdc` files in the appropriate rules directory
2. Rules will be automatically copied to `.cursor/rules/` when running the setup script

### Adding New Skills

1. Create a skill directory in `.cursor/shared/skills/your-skill-name/`
2. Add a `SKILL.md` file with YAML frontmatter and instructions
3. Optionally add `scripts/`, `references/`, or `assets/` directories
4. Skills will be automatically copied to `.cursor/skills/`, `.claude/skills/`, and `.codex/skills/` when running the setup script for cross-platform compatibility
5. See [SKILLS.md](SKILLS.md) for detailed documentation

### Directory Structure

-   `bin/setup-cursor.sh`: Main setup script
-   `.cursor/shared/rules/`: Shared base rules
-   `.cursor/shared/skills/`: Shared skills (installable workflows)
-   `.cursor/frontend/rules/`: Frontend-specific rules
-   `.cursor/frontend-lib/rules/`: Frontend library-specific rules
-   `.cursor/backend/rules/`: Backend-specific rules

## Skills

This repository includes example Cursor Skills that can be installed:

- **prep-for-pr**: Prepare your branch for a PR by checking and fixing code quality issues
- **review-pr**: Systematically review someone else's PR with code quality, security, and standards checks
- **address-pr-feedback**: Find PR by branch, review feedback, create plan, implement fixes, and resolve GitHub conversations
- **check-and-fix-ci**: Find PR for current branch, check CI status, fix non-transient failures, and push (invoke with `/check-and-fix-ci`)

See [SKILLS.md](SKILLS.md) for complete documentation on:
- Creating new skills
- Installing skills from GitHub
- Skill structure and format
- Best practices

## License

[Add your license information here]