rules-for-ai

Rules for AI

Portable rules and skills for AI coding agents.

Write your rules once and carry them across Claude Code and Cursor as an installable, updatable plugin — no more copy-pasting the same instructions into every machine and repository. Language preferences for issues, pull requests, comments, logs, and test logs are resolved per user and overridden per project. Use it as is, or fork it and swap in your own rules.

Getting Started

rules-for-ai.sh installs, updates, and uninstalls everything. Choose a platform — claude or cursor — and a scope.

Scopes

Scope	Meaning
user	Every project on this machine
project	One repo, shared with your team via git
local	One repo, just you, nothing committed

flowchart LR
  Q{Who shares this?}
  Q -->|Only me| L[local]
  Q -->|My team| P[project]
  Q -->|All my projects| U[user]

Without cloning

curl -fsSL https://raw.githubusercontent.com/hashiiiii/rules-for-ai/main/rules-for-ai.sh | sh -s -- <install|uninstall> <claude|cursor> <user|project|local> [path/to/repo]
# e.g. curl -fsSL https://raw.githubusercontent.com/hashiiiii/rules-for-ai/main/rules-for-ai.sh | sh -s -- install claude user

From a clone

./rules-for-ai.sh <install|uninstall> <claude|cursor> <user|project|local> [path/to/repo]
# e.g. ./rules-for-ai.sh install cursor project path/to/repo

path/to/repo applies to project and local only and defaults to the current directory. Re-running install updates in place. Uninstall removes exactly what install created.

What each platform puts where, and how locale reaches the model, is in Platform details.

Locale

Language preferences live in one user-level file: ~/.config/rules-for-ai/LOCALE.md. You can ask the agent to set your locale and the hashiiiii-locale skill (it ships with every install) writes the file with all five keys (POSIX-style tags such as ja_JP or en_US):

Key	Artifact
issues	Issues
pull-requests	Pull requests
comments	Code comments
logs	Log messages
test-logs	Test log messages

Tell it one tag for everything (ja_JP) or one per artifact (issues=ja_JP pull-requests=ja_JP comments=ja_JP logs=en_US test-logs=en_US). The skill only ever writes the user-level file — never a file inside a project.

Two layers decide the effective language:

1. Project instructions — a repo's own CLAUDE.md / AGENTS.md language policy always wins when present.
2. Resolved keys — otherwise the first existing file wins as a whole; layers never merge:

• ~/.config/rules-for-ai/LOCALE.md (respect $XDG_CONFIG_HOME when set) — the file the skill maintains
• the bundled LOCALE.default.md that every install ships — where each layout places it is in Platform details
• an inline en_US default for all keys

One shared resolver implements this chain on both platforms and at every scope; only the location of the bundled default differs per install layout. A session hook injects the resolved keys into context. There is no project-level LOCALE.md. A file at the project root is ignored. Put project-specific language policy in that project's CLAUDE.md / AGENTS.md instead.

Platform details

• Claude Code — settings paths, SessionStart injection, locale resolution
• Cursor — per-scope files, hooks.json, how locale reaches context

Updates

Re-run the same install command (or the curl one-liner). Claude Code can also run /plugin marketplace update hashiiiii.

Fork and customize

Fork, edit AGENTS.md and skills/, then install from your fork instead of hashiiiii/rules-for-ai.

Skills use the hashiiiii- prefix. Rename to your own and find every reference:

grep -rl 'hashiiiii-' .

Also set REPO in rules-for-ai.sh and repository in .claude-plugin/plugin.json.

Releasing (maintainers)

Releases are cut from the Actions tab — no local tagging.

1. Open Actions → release → Run workflow, keep main selected, and enter the version as X.Y.Z (no v prefix).
2. The workflow bumps version in both plugin manifests, commits chore: release vX.Y.Z, tags it, and creates the GitHub release with generated notes.

The release commit is authored by a GitHub App, so a one-time setup is required: install the App on this repo, add its APP_CLIENT_ID / APP_PRIVATE_KEY secrets, and add the App to the main ruleset's bypass actors so it can push the commit past the pull-request requirement.

License

MIT