Proposal: Standardized rule format for .agents/rules/

[rameshsunkara]

Related: #71

I work at NVIDIA, here different teams use different coding agents -- Claude Code, Cursor, Codex and so on. We keep running into the same problem: the same coding conventions end up copied into .claude/rules/, .cursor/rules/ and other tool-specific directories. I believe this overhead or nuance is more prevalent in open source community where tools differ widely. The formats are close, but not quite the same:

Tool	Rules Location	Path-Scoping Field
Claude Code	.claude/rules/*.md	paths:
Cursor	.cursor/rules/*.mdc	globs:
Windsurf	.windsurf/rules/*.md	globs:
GitHub Copilot	.github/instructions/*.instructions.md	applyTo:
Cline	.clinerules/*.md	paths:
JetBrains AI Assistant	.aiassistant/rules/*.md	(IDE-managed)
Amazon Q	.amazonq/rules/*.md	(none)

Bridging tools like Rulesync exist to generate all of these from a single source, which is useful, but also a sign that the underlying problem is real.

AGENTS.md already handles the "here's how this project works" layer. Agent Skills handles reusable capabilities. But for path-scoped rules specifically -- "when touching API files, follow these conventions" -- there's nothing shared. Every tool rolled their own.

What I'm proposing

A shared file format for .agents/rules/. Not a new standard to compete with AGENTS.md, more a companion spec for the structured bits that don't belong in a freeform markdown file.

Cursor already reads from .agents/skills/, so the directory has some cross-tool precedent.

The format is markdown with optional YAML frontmatter -- the same general shape several tools already use for project rules, just with standardized field names:

---
description: Backend API conventions -- only loaded when touching API files
trigger: auto
paths:
  - "src/api/**"
  - "src/routes/**"
---

- Validate all request bodies with zod schemas before processing
- Return errors as `{ error: string, code: number }` -- no free-form messages
- Use `requireAuth` middleware, don't check tokens manually
- Every new endpoint needs an integration test in `tests/api/`

The core frontmatter fields (name, description, trigger, paths) are meant to capture the common subset that already exists across tools. I'm also proposing keywords, priority, and tags as additions that seem useful in practice:

Field	Type	Description
name	string	Kebab-case identifier (default: filename stem)
description	string	What this rule covers
trigger	always | auto | manual	When the rule loads (default: always)
paths	string[]	Glob patterns for file-scoped activation
keywords	string[]	Prompt keywords for activation
priority	integer	Conflict resolution -- higher wins
tags	string[]	Organizational grouping (no semantic effect)

The mapping to existing tools looks pretty straightforward in the common cases -- rename globs to paths, map alwaysApply: true to trigger: always, and so on. There are still tool-specific edges, and I've tried to spell those out in the spec repo instead of hand-waving them away.

Directory layout

project-root/
├── AGENTS.md                    # Instructions (unchanged)
├── .agents/
│   ├── rules/                   # Shared rules (this proposal)
│   │   ├── code-style.md
│   │   └── api-conventions.md
│   ├── skills/                  # Agent Skills (existing standard)
│   │   └── deploy/SKILL.md
│   └── local/                   # .gitignored personal overrides
│       └── rules/

Instead of maintaining 6 tool-specific copies of code-style.md, you'd have one in .agents/rules/.

What I looked at before writing this

• Proposal: Standardize a .agent Directory for Comprehensive Project Context #71 proposes a .agent directory for project context -- this feels like a narrower, more incremental take on part of that idea
• agentsfolder/spec tried a comprehensive .agents/ spec, but I think it covered too much at once
• aicodingrules.org proposed a YAML-first rule format -- thoughtful work, but most tools seem to have landed on markdown-first

Things I'm not sure about

• Should there be a fourth trigger mode where the agent decides whether to load a rule based on its description? Cursor and Windsurf both support something like this, but adding it complicates the spec.
• Is .agents/manifest.json worth it for monorepo discovery hints, or is that premature?
• The realistic adoption path is probably: tools read .agents/rules/ as an additional source alongside their existing directories, and then we see if things converge over time. I don't think deprecating tool-specific directories is realistic any time soon.

Full spec with examples, JSON Schema for frontmatter validation, and per-tool compatibility mappings: ink to repo

-- Ramesh Sunkara, NVIDIA (personal capacity)