Skip to content

generic-automation-and-it/smooth-ai-stockanalysis / .agents/skills/manage-rule-system

manage-rule-system

Verified

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, 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).

LocationUse 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:

  1. Use .instructions.md extension (kebab-case filename)
  2. 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.

FieldUsed byPurpose
descriptionCopilot, CursorDisplayed in UI; Cursor uses it for agent-mode rule selection
globsCursorFile pattern for auto-attach; quote the value
pathsClaude CodeYAML list of file patterns for path-scoped applicability. Mirror globs. Use ["**"] for always-apply
applyToCopilotFile pattern for .github/instructions/** loading. Mirror globs; use '**' for always-apply
alwaysApplyCursortrue = 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 scopePlace inalwaysApplyglobs / paths / applyTo
Project-wide (git, PR, workflow).agents/rules/ (flat) or a category foldertrue"**"
Backend only.agents/rules/backend/false"**/*.cs"
Domain-specificnearest *AGENTS.md insteadn/an/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 ## Changelog table (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 in smooth-ai-stockanalysis.slnx

Tool Compatibility Matrix

ToolReads fromScoping mechanismExtension
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 explicitlyAGENTS.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/applyTo frontmatter 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 in load-agents-context.sh and skill docs).
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall