generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/manage-rule-system
manage-rule-system
VerifiedConvention 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, and OpenAI Codex.
Manage 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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |