manage-rule-system
Convention for creating, updating, or modifying rule files in .agents/rules/. Use when adding, editing, or restructuring rule files to ensure compatibility across Claude Code, GitHub Copilot, Cursor,
SKILL.md.agents/skills/manage-rule-system/SKILL.md
GitHubManage Rule System — Skill
Triggered automatically by .agents/hooks/manage-rule-system-context.sh (UserPromptSubmit) when the user mentions creating, updating, modifying, adding, or editing a rule. Also triggers when an agent Reads/Edits/Writes a file under .agents/rules/ via the load-agents-context PostToolUse hook.
Rule Directory
All rule files live under a single .agents/rules/ tree, organized into category subfolders. Every .md file in the tree is auto-loaded by the AI tool at session start; applicability is scoped per-file via the paths/globs/applyTo frontmatter (there is no separate scoped/injected directory).
| Location | Use for |
|---|---|
.agents/rules/*.instructions.md (flat) |
Cross-cutting rules that don't share a category with ≥1 other rule (AI workflow, code-review false-positive guidance, project overview) |
.agents/rules/<category>/ |
A category folder is created when 2+ rules share a topic. Current: backend/ (.NET / EF Core / API+Mediator / migrations / WireMock / logging), git/ (git policy, PR standards), meta/ (rule-file convention, AGENTS.md quality) |
To make a rule narrow to certain files, set its frontmatter scope fields (e.g. paths: ["**/*.cs"]); to make it always-apply, use "**" / alwaysApply: true. The folder is organizational only — it does not change loading.
To defer a prompt-scoped rule for Claude only (saving session tokens) and re-inject it on demand via a UserPromptSubmit hook, see "Hook-deferred rules" in .agents/rules/meta/rules.instructions.md — e.g. code-review-standards.
File Format
Every rule file MUST:
- Use
.instructions.mdextension (kebab-case filename) - Include YAML frontmatter (Copilot/Cursor metadata)
Frontmatter Template
---
description: 'Short description of what the rule covers'
globs: "<glob-pattern>"
paths:
- "<glob-pattern>"
applyTo: '<glob-pattern>'
alwaysApply: <true|false>
---
The three scope fields mirror the same pattern(s) — one per tool. For multiple patterns, globs/applyTo take a comma-separated string while paths takes a YAML list.
| Field | Used by | Purpose |
|---|---|---|
description |
Copilot, Cursor | Displayed in UI; Cursor uses it for agent-mode rule selection |
globs |
Cursor | File pattern for auto-attach; quote the value |
paths |
Claude Code | YAML list of file patterns for path-scoped applicability. Mirror globs. Use ["**"] for always-apply |
applyTo |
Copilot | File pattern for .github/instructions/** loading. Mirror globs; use '**' for always-apply |
alwaysApply |
Cursor | true = always loaded; false = only on glob match |
Claude Code auto-loads every .md file under .claude/rules/ (symlink → .agents/rules/ → .github/instructions/) at session start, recursing into category subfolders. Scoping is per-file via the frontmatter above — there is no separate injected directory.
Scoping Guidelines
| Rule scope | Place in | alwaysApply |
globs / paths / applyTo |
|---|---|---|---|
| Project-wide (git, PR, workflow) | .agents/rules/ (flat) or a category folder |
true |
"**" |
| Backend only | .agents/rules/backend/ |
false |
"**/*.cs" |
| Domain-specific | nearest *AGENTS.md instead |
n/a | n/a |
Create a <category>/ subfolder when 2+ rules share a topic; otherwise keep the rule flat in .agents/rules/.
Creating a New Rule
touch .agents/rules/my-new-rule.instructions.md # cross-cutting (flat)
touch .agents/rules/backend/my-rule.instructions.md # backend category
Then add frontmatter + content. After saving:
- Add a one-line changelog entry inside the rule file's
## Changelogtable (this repo retains in-file changelogs; the AI loading note tells agents to skip the section at runtime) - If you created a new category folder, reflect it in root
AGENTS.md(Rules section) and insmooth-ai-stockanalysis.slnx
Tool Compatibility Matrix
| Tool | Reads from | Scoping mechanism | Extension |
|---|---|---|---|
| Claude Code | .claude/rules/ (symlink → .agents/rules/ → .github/instructions/) |
paths frontmatter |
.md |
| Copilot | .github/instructions/ (real directory — no symlink) |
applyTo frontmatter |
.instructions.md |
| Cursor | .cursor/rules/ (symlink → .agents/rules/ → .github/instructions/) |
globs + alwaysApply frontmatter |
.instructions.md |
| Codex | .codex/ (symlink → .agents/) |
invokes context-load-agents-context skill explicitly |
AGENTS.md |
The rule files physically live in .github/instructions/ (a real directory, so Copilot's github.com-hosted agent reads them without resolving a symlink). .agents/rules, .claude/rules, and .cursor/rules are symlinks resolving back to it — all tools share one source of truth.
Non-Negotiables
- Scope per-file, not per-directory. Every rule carries
paths/globs/applyTofrontmatter that mirrors the same pattern(s). Category subfolders are organizational only and do not affect loading. - Never reference a moved rule by its old path. After moving a rule, sweep cross-references with
rg -l <old-path>and update every hit (including hardcoded paths inload-agents-context.shand skill docs).