Rule Configuration
Config fields, metadata files, versioning, and more.
Config Fields
The agentrules.json file created by init supports these fields:
| Field | Required | Description |
|---|---|---|
name | Yes | URL-safe identifier (lowercase, hyphens only) |
title | Yes | Display name shown in the registry |
description | No | Short description (max 500 characters; recommended) |
license | Yes | SPDX license identifier (e.g., MIT, Apache-2.0) |
platforms | Yes | Array of target platforms: opencode, claude, cursor, codex |
type | No | Rule type: instruction, rule, command, skill, agent, tool |
version | No | Major version (default: 1) |
tags | No | 0-10 tags for discoverability (lowercase with hyphens; recommended) |
features | No | Up to 5 key features to highlight |
ignore | No | Glob patterns to exclude from bundle |
Example:
{
"$schema": "https://agentrules.directory/schema/agentrules.json",
"name": "my-rule",
"title": "My Awesome Rule",
"description": "A helpful rule for TypeScript projects",
"license": "MIT",
"platforms": ["opencode"],
"tags": ["typescript", "testing", "tdd"],
"features": [
"Code review agent",
"Test generation commands",
"PR description generator"
]
}Structuring Your Rule
Single platform
Files are placed under the platform directory automatically:
my-rule/
├── agentrules.json
└── commands/
└── deploy.mdInstalls as .claude/commands/deploy.md or .opencode/commands/deploy.md.
Multi-platform
When publishing to multiple platforms with different content, use path to specify source directories:
my-rule/
├── agentrules.json
├── claude/
│ └── commands/
│ └── deploy.md
└── opencode/
└── commands/
└── deploy.md{
"platforms": [
{ "platform": "claude", "path": "claude" },
{ "platform": "opencode", "path": "opencode" }
]
}If the content is the same for all platforms, just list them:
{
"platforms": ["claude", "opencode"]
}Skills
For multi-file skills, set type: "skill" and structure files naturally:
my-skill/
├── agentrules.json
├── SKILL.md
├── scripts/
│ └── helper.py
└── references/
└── api.md{
"name": "my-skill",
"type": "skill",
"platforms": ["claude", "opencode"],
...
}Files are automatically placed in the correct skill directory for each platform (e.g., .claude/skills/my-skill/...).
See agentskills.io for the skills standard.
Metadata Files
Metadata lives next to agentrules.json (rule root):
my-rule/
├── agentrules.json
├── README.md <- Displayed on your rule's registry page (optional)
├── LICENSE.md <- Full license text (optional)
└── INSTALL.txt <- Message shown after install (optional)These files are not installed into the user's project. They are published as metadata fields (readmeContent, licenseContent, installMessage).
README.md, LICENSE.md (or LICENSE.txt), and INSTALL.txt are reserved metadata filenames at the rule root and are excluded from the bundled files list.
Ignoring Files
Some files are automatically excluded:
node_modules/,.git/,.DS_Store- Lock files (
package-lock.json,bun.lockb, etc.) agentrules.jsonitselfREADME.md,LICENSE.md,INSTALL.txt(metadata files; not bundled)
Add custom exclusions with the ignore field:
{
"ignore": ["*.log", "test-fixtures/", "*.tmp"]
}Versioning
Rules use MAJOR.MINOR versioning:
- You control the major version — bump when you make breaking changes
- The registry auto-increments minor — each publish gets the next minor
# Publish to major version 1 (default)
npx @agentrules/cli publish
# Publish to major version 2 (breaking changes)
npx @agentrules/cli publish --version 2Users can install specific versions:
npx @agentrules/cli add my-rule@1.0 -p opencode # Specific version
npx @agentrules/cli add my-rule -p opencode # Latest overallUnpublishing
Remove a specific version from the registry:
npx @agentrules/cli unpublish my-rule@1.0Unpublished versions cannot be republished with the same version number.
Authentication
| Command | Description |
|---|---|
npx @agentrules/cli login | Authenticate with the registry |
npx @agentrules/cli logout | Log out and clear credentials |
npx @agentrules/cli whoami | Show current user |