npm package: @render-lab/ai-rules
Description: Install agent rules and skills from any GitHub repo.
Author: render-lab
Latest version: 0.1.0

# ai-rules

> **Experimental.** This project is in early development. Commands, config format, and APIs may change between releases.

Install agent rules and skills from any GitHub repo. One CLI for every AI coding agent.

```
npx @render-lab/ai-rules init
```

## Supported agents

- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- OpenCode
- Cline
- Roo Code
- Amp
- Gemini CLI

## How it works

GitHub is the registry. Any public repo with a `rules/`, `skills/`, or `linters/` directory is a valid rule set. `ai-rules` fetches content from the GitHub API, merges rules into your agent's rules file, and tracks what you've installed.

Rules are wrapped in comment markers so they can be updated or removed without touching the rest of your rules file:

```markdown
<!-- ai-rules: owner/repo -->
## Security
- Never hardcode secrets
<!-- /ai-rules: owner/repo -->
```

Skills (SKILL.md packages) are copied into your agent's skill directory. Linter configs are copied to the project root.

## Getting started

### Install globally

```bash
npm install -g @render-lab/ai-rules
```

After installing globally, the command is just `ai-rules`:

```bash
ai-rules init
```

### Or run with npx

```bash
npx @render-lab/ai-rules init
```

### Initialize your project

```bash
ai-rules init
```

This detects your AI coding agent, creates a rules file, and sets up `.ai-rules.json` to track installed content. You can also pick from a curated catalog of popular rule sets during init.

## Popular rule sets

Install any of these with `ai-rules add rule <repo>`:

| Repo | Description |
|---|---|
| [renderinc/opinionated-vibe-coding](https://github.com/renderinc/opinionated-vibe-coding) | Agent rules for disciplined AI-assisted development |
| [lirantal/agent-rules](https://github.com/lirantal/agent-rules) | Curated collection of agent rules for secure, quality code |
| [anthropics/claude-code-best-practices](https://github.com/anthropics/claude-code-best-practices) | Official best practices for Claude Code from Anthropic |
| [PatrickJS/awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) | Community-curated Cursor rules for various frameworks |
| [pontusab/cursor.directory](https://github.com/pontusab/cursor.directory) | Cursor rules for your framework and language |

## Popular skills

Install any of these with `ai-rules add skill <repo>`:

| Repo | Skills | Description |
|---|---|---|
| [render-oss/skills](https://github.com/render-oss/skills) | render-deploy, render-debug, render-monitor, render-migrate-from-heroku, render-workflows | Deploy, debug, and monitor apps on Render |
| [renderinc/opinionated-vibe-coding](https://github.com/renderinc/opinionated-vibe-coding) | ovc-audit, ovc-scorecard, ovc-security-review, ovc-dry-check, ovc-dependency-check, ovc-setup | Codebase audits, scorecards, and security reviews |

> Run `ai-rules add skill <repo> --list` to see all available skills in a repo before installing.

## Commands

### `ai-rules init`

Detect your agent and create a rules file. If multiple agents are installed, choose which ones to set up.

### `ai-rules add rule [repo]`

Add rules from a GitHub repo in `owner/repo` format. Without an argument, shows a curated catalog to pick from.

```bash
ai-rules add rule renderinc/opinionated-vibe-coding
ai-rules add rule https://github.com/lirantal/agent-rules
```

### `ai-rules add skill <source>`

Add skills from a GitHub repo. Skills are SKILL.md packages with optional reference files.

```bash
ai-rules add skill render-oss/skills
ai-rules add skill render-oss/skills --skill render-deploy
ai-rules add skill render-oss/skills --list
ai-rules add skill render-oss/skills --global
```

Options:

- `-s, --skill <name>` — Install a specific skill by name
- `-a, --agent <agent>` — Target a specific agent
- `-g, --global` — Install to the global skill directory
- `-l, --list` — List available skills without installing
- `--copy` — Copy files instead of symlinking

### `ai-rules remove rule [repo]`

Remove an installed rule set. Without an argument, shows a picker.

### `ai-rules remove skill [name]`

Remove an installed skill and its files. Without an argument, shows a picker.

### `ai-rules update [repo]`

Update installed rules and skills to the latest version. Pass a repo slug to update a specific one, or omit to update all.

```bash
ai-rules update
ai-rules update renderinc/opinionated-vibe-coding
```

### `ai-rules list`

List all installed rule sets and skills with their source, version, and install date.

### `ai-rules doctor`

Diagnose your setup. Checks for a valid config file, detected agent, rules file, installed agents on the system, marker integrity, skill directory existence, and GitHub token status.

## Publishing a rule set

To make your repo installable with `ai-rules`, add one or more of these directories:

```
my-rules/
├── rules/           # Agent rules files
│   ├── CLAUDE.md
│   ├── .cursorrules
│   └── .windsurfrules
├── skills/          # SKILL.md packages
│   └── my-skill/
│       ├── SKILL.md
│       └── references/
│           └── guide.md
├── linters/         # Linter configs
│   └── biome.json
└── ai-rules.json    # Optional manifest
```

The optional `ai-rules.json` manifest provides metadata:

```json
{
  "name": "My Rules",
  "description": "A set of rules for disciplined development",
  "tags": ["security", "best-practices"]
}
```

## Configuration

`ai-rules` stores its state in `.ai-rules.json` at the project root. This file tracks the detected agent, rules file path, installed rule sets (with commit SHAs), and installed skills.

## Requirements

- Node.js 20 or later

## License

MIT