Rule Author
Canonical workflow, templates, and references for authoring AI coding assistant rules. Supports GitHub Copilot, Cursor, and Claude Code.
Internal skill. Users interact via the fusion-rules gateway, which routes to editor-specific agents that follow the workflow defined here.
Scope
This skill provides:
- Workflow (Steps 1–7 below) — the guided authoring process
- Templates (
assets/) — starter files for each editor format
- References (
references/) — tech-stack examples
It does not provide agents. Agents live in fusion-rules/agents/ and reference this skill's assets and workflow.
Required inputs
Mandatory
Gathered during interview
Instructions
Step 1 — Assess current state
Check the repository for existing rule files:
.github/copilot-instructions.md
.github/instructions/*.instructions.md
.cursor/rules/*.md
.cursor/rules/*.mdc
.cursor/rules/**/*.md
.cursor/rules/**/*.mdc
CLAUDE.md
.claude/CLAUDE.md
.claude/rules/*.md
.claude/rules/**/*.md
Report what exists, what is missing, and whether updates or new files are needed.
Step 2 — Scan repository
Before interviewing, scan for existing documentation and configuration that encodes conventions. Extract actionable directives from:
Documentation files:
README.md — project overview, setup, tech stack
CONTRIBUTING.md — code style, PR workflow, commit conventions
AGENTS.md, CLAUDE.md — existing AI instructions
docs/adr/**, adr/**, docs/decisions/** — Architecture Decision Records
docs/**/*.md — developer guides, onboarding docs, style guides
SECURITY.md — security policies
CODE_OF_CONDUCT.md — collaboration guidelines (rarely rule-relevant)
Configuration files:
package.json / pyproject.toml / *.csproj — tech stack, scripts, dependencies
tsconfig.json / jsconfig.json — language settings, strictness
biome.json / .eslintrc* / .prettierrc* / ruff.toml / .editorconfig — formatting and linting
.github/workflows/*.yml — CI checks, required validations, test commands
Dockerfile / docker-compose.yml — runtime environment
Makefile / Justfile / Taskfile.yml — build and task commands
Code patterns (sample, don't exhaustively read):
- Entry points (
src/index.*, src/main.*, app.*) — architecture patterns
- Test files — testing framework, naming conventions, file placement
- Directory structure — architectural boundaries, feature organization
For each source, extract:
- Concrete conventions that can become imperative directives
- Build/test/lint commands the AI should know
- Architecture boundaries or patterns to follow
- Explicit "do this / don't do that" rules
Skip:
- Implementation details that change frequently
- Content that restates language/framework defaults
- Aspirational rules not enforced by CI or team practice
Present summary of discovered conventions to the developer, organized by area, before proceeding to the interview.
Step 3 — Interview (fill gaps)
Use scan results to skip areas already well-documented. Ask focused questions only for gaps. Cover these areas one at a time:
- Tech stack — languages, frameworks, runtime, package manager
- Code style — naming conventions, formatting rules, import ordering
- Architecture — project structure, key patterns (MVC, hexagonal, etc.)
- Testing — framework, conventions, coverage expectations
- Documentation — inline comments style, doc generation, README standards
- Git workflow — branch naming, commit message format, PR expectations
- Security — sensitive data handling, auth patterns, compliance rules
- Path-specific concerns — directories or file types needing specialized guidance
For each area, present what the scan found and ask: "Is this accurate? Anything to add or correct?" Don't re-ask for information already captured.
For each convention needing deeper context, use follow-up questions in assets/creation-follow-up.md — purpose, exceptions, boundaries, voice.
Step 4 — Classify guidance
Separate the gathered conventions into buckets:
GitHub Copilot:
| Bucket |
Target file |
When it activates |
| Always-on conventions |
.github/copilot-instructions.md |
Every Copilot interaction |
| Scoped conventions |
.github/instructions/<name>.instructions.md |
Only when matching files are open/referenced |
Cursor:
| Bucket |
Target file |
When it activates |
| Always-on conventions |
.cursor/rules/<name>.mdc with alwaysApply: true |
Every Cursor Agent session |
| Auto-attached conventions |
.cursor/rules/<name>.mdc with globs |
When matching files are in context |
| Agent-selected conventions |
.cursor/rules/<name>.mdc with description only |
When the Agent decides it is relevant |
| Manual conventions |
.cursor/rules/<name>.mdc (no alwaysApply, no globs) |
Only when @-mentioned in chat |
Claude Code:
| Bucket |
Target file |
When it activates |
| Always-on conventions |
CLAUDE.md or .claude/CLAUDE.md |
Every Claude Code session |
| Scoped conventions |
.claude/rules/<name>.md with paths frontmatter |
When Claude reads matching files |
| Unconditional rule |
.claude/rules/<name>.md (no paths) |
Every session (like always-on) |
Decision rule: If a convention applies to all files in the repo, it belongs in root / always-on instructions. If it applies only to specific paths or file types, create a scoped rule.
When targeting multiple editors, generate parallel files with equivalent content — do not duplicate guidance within a single editor's files.
Step 5 — Draft rule files
Generate files using templates in assets/:
GitHub Copilot:
- Root instructions: use
assets/copilot-instructions-template.md
- Scoped instructions: use
assets/scoped-rule-template.md with correct applyTo glob
Cursor:
- Use
assets/cursor-rule-template.mdc and set frontmatter accordingly
Claude Code:
- Project instructions: use
assets/claude-rule-template.md
- Scoped rules: place in
.claude/rules/ with paths frontmatter
Quality rules (enforced during drafting):
- Keep instructions concise — actionable directives, not explanations
- Use imperative voice ("Use camelCase for variables", not "Variables should use camelCase")
- Avoid duplicating guidance between root and scoped files
- Validate
applyTo / globs / paths glob patterns match intended files
- Warn if total root instructions exceed ~80 lines (risk of context dilution)
- Warn if scoped instruction file exceeds ~50 lines (GitHub Copilot), ~500 lines (Cursor), ~200 lines (Claude Code CLAUDE.md)
- See
references/examples.md for concrete good/bad examples
- See
assets/quality-checklist.md for full checklist
Step 6 — Review and refine
Present drafted files to the developer. For each file:
- Show full content
- Highlight quality warnings (length, broad globs, duplication)
- Ask for approval or edits
Step 7 — Write files
After approval, write rule files to the repository. Create .github/instructions/, .cursor/rules/, and/or .claude/rules/ directories as needed.
Confirm final file list and paths before writing.
Expected output
.github/copilot-instructions.md — root instructions file (created or updated)
.github/instructions/*.instructions.md — zero or more scoped instruction files
.cursor/rules/*.mdc — zero or more Cursor rule files (when Cursor is targeted)
CLAUDE.md or .claude/CLAUDE.md — project instructions (when Claude Code is targeted)
.claude/rules/*.md — zero or more Claude Code scoped rule files
- Summary of what was created/updated and why
Instructions vs skills vs rules — when to use which
| Need |
GitHub Copilot |
Cursor |
Claude Code |
| Always-on coding conventions |
copilot-instructions.md |
.cursor/rules/*.mdc with alwaysApply: true |
CLAUDE.md |
| File/path-specific guidance |
.github/instructions/*.instructions.md |
.cursor/rules/*.mdc with globs |
.claude/rules/*.md with paths |
| Task-specific multi-step workflows |
A skill (SKILL.md) |
.cursor/rules/*.mdc (manual or agent-selected) |
Skills / subagents |
| Agent routing and orchestration |
Agent definitions (.agent.md) |
.cursor/rules/*.mdc with description |
Subagent configs |
| Simple project-wide instructions |
copilot-instructions.md |
AGENTS.md |
CLAUDE.md |
Instructions and rules shape how the AI writes code. Skills define what it can do as structured tasks.
Safety and constraints
Never:
- Embed secrets, tokens, or credentials in rule files
- Generate rules that contradict repository security policies
- Overwrite existing files without showing the diff and getting approval
- Invent conventions — only document what the developer confirms
Always:
- Show drafts before writing any files
- Validate glob patterns against actual repository paths
- Warn on overly broad globs (e.g.,
**/* captures everything)
- Keep instructions concise and actionable
- Preserve existing content when updating (append or merge, never replace silently)
References
references/examples.md — concrete examples for different tech stacks
assets/creation-follow-up.md — per-rule follow-up questions (purpose, exceptions, boundaries, voice)
assets/frontmatter-scenarios.md — scenario-based frontmatter guide for GitHub Copilot, Cursor, and Claude Code
assets/copilot-instructions-template.md — starter template for root instructions
assets/scoped-rule-template.md — starter template for scoped rules
assets/cursor-rule-template.mdc — starter template for Cursor rules
assets/claude-rule-template.md — starter template for Claude Code rules
assets/quality-checklist.md — quality review checklist
1---2name: fusion-rule-author3description: 'Support skill providing the workflow, templates, and references for AI coding assistant rule authoring. Invoked by fusion-rules gateway agents — not intended for direct use.'4license: MIT5metadata:6 source: https://skillmd.com/skills/equinor/fusion-rule-author7 version: "0.1.1"8 status: active9 owner: "@equinor/fusion-core"10 role: support11 tags:12 - copilot13 - cursor14 - claude-code15 - rules16 - developer-experience17 - onboarding18 - repository-setup19 - system20---2122# Rule Author2324Canonical workflow, templates, and references for authoring AI coding assistant rules. Supports **GitHub Copilot**, **Cursor**, and **Claude Code**.2526> **Internal skill.** Users interact via the `fusion-rules` gateway, which routes to editor-specific agents that follow the workflow defined here.2728## Scope2930This skill provides:3132- **Workflow** (Steps 1–7 below) — the guided authoring process33- **Templates** (`assets/`) — starter files for each editor format34- **References** (`references/`) — tech-stack examples3536It does **not** provide agents. Agents live in `fusion-rules/agents/` and reference this skill's assets and workflow.3738## Required inputs3940### Mandatory4142- [ ] Repository context (working directory or repo URL)4344### Gathered during interview4546- [ ] Tech stack (languages, frameworks, build tools)47- [ ] Code conventions (naming, formatting, patterns)48- [ ] Testing expectations (framework, coverage, style)49- [ ] Documentation preferences (comments, TSDoc/JSDoc, README standards)50- [ ] Commit and PR conventions51- [ ] Error handling patterns52- [ ] Security or compliance constraints53- [ ] File/path-specific conventions that need scoped rules5455## Instructions5657### Step 1 — Assess current state5859Check the repository for existing rule files:6061```62.github/copilot-instructions.md63.github/instructions/*.instructions.md64.cursor/rules/*.md65.cursor/rules/*.mdc66.cursor/rules/**/*.md67.cursor/rules/**/*.mdc68CLAUDE.md69.claude/CLAUDE.md70.claude/rules/*.md71.claude/rules/**/*.md72```7374Report what exists, what is missing, and whether updates or new files are needed.7576### Step 2 — Scan repository7778Before interviewing, scan for existing documentation and configuration that encodes conventions. Extract actionable directives from:7980**Documentation files:**81- `README.md` — project overview, setup, tech stack82- `CONTRIBUTING.md` — code style, PR workflow, commit conventions83- `AGENTS.md`, `CLAUDE.md` — existing AI instructions84- `docs/adr/**`, `adr/**`, `docs/decisions/**` — Architecture Decision Records85- `docs/**/*.md` — developer guides, onboarding docs, style guides86- `SECURITY.md` — security policies87- `CODE_OF_CONDUCT.md` — collaboration guidelines (rarely rule-relevant)8889**Configuration files:**90- `package.json` / `pyproject.toml` / `*.csproj` — tech stack, scripts, dependencies91- `tsconfig.json` / `jsconfig.json` — language settings, strictness92- `biome.json` / `.eslintrc*` / `.prettierrc*` / `ruff.toml` / `.editorconfig` — formatting and linting93- `.github/workflows/*.yml` — CI checks, required validations, test commands94- `Dockerfile` / `docker-compose.yml` — runtime environment95- `Makefile` / `Justfile` / `Taskfile.yml` — build and task commands9697**Code patterns (sample, don't exhaustively read):**98- Entry points (`src/index.*`, `src/main.*`, `app.*`) — architecture patterns99- Test files — testing framework, naming conventions, file placement100- Directory structure — architectural boundaries, feature organization101102**For each source, extract:**1031. Concrete conventions that can become imperative directives1042. Build/test/lint commands the AI should know1053. Architecture boundaries or patterns to follow1064. Explicit "do this / don't do that" rules107108**Skip:**109- Implementation details that change frequently110- Content that restates language/framework defaults111- Aspirational rules not enforced by CI or team practice112113Present summary of discovered conventions to the developer, organized by area, before proceeding to the interview.114115### Step 3 — Interview (fill gaps)116117Use scan results to skip areas already well-documented. Ask focused questions only for gaps. Cover these areas one at a time:1181191. **Tech stack** — languages, frameworks, runtime, package manager1202. **Code style** — naming conventions, formatting rules, import ordering1213. **Architecture** — project structure, key patterns (MVC, hexagonal, etc.)1224. **Testing** — framework, conventions, coverage expectations1235. **Documentation** — inline comments style, doc generation, README standards1246. **Git workflow** — branch naming, commit message format, PR expectations1257. **Security** — sensitive data handling, auth patterns, compliance rules1268. **Path-specific concerns** — directories or file types needing specialized guidance127128For each area, present what the scan found and ask: "Is this accurate? Anything to add or correct?" Don't re-ask for information already captured.129130For each convention needing deeper context, use follow-up questions in `assets/creation-follow-up.md` — purpose, exceptions, boundaries, voice.131132### Step 4 — Classify guidance133134Separate the gathered conventions into buckets:135136**GitHub Copilot:**137138| Bucket | Target file | When it activates |139|--------|-------------|-------------------|140| **Always-on** conventions | `.github/copilot-instructions.md` | Every Copilot interaction |141| **Scoped** conventions | `.github/instructions/<name>.instructions.md` | Only when matching files are open/referenced |142143**Cursor:**144145| Bucket | Target file | When it activates |146|--------|-------------|-------------------|147| **Always-on** conventions | `.cursor/rules/<name>.mdc` with `alwaysApply: true` | Every Cursor Agent session |148| **Auto-attached** conventions | `.cursor/rules/<name>.mdc` with `globs` | When matching files are in context |149| **Agent-selected** conventions | `.cursor/rules/<name>.mdc` with `description` only | When the Agent decides it is relevant |150| **Manual** conventions | `.cursor/rules/<name>.mdc` (no `alwaysApply`, no `globs`) | Only when @-mentioned in chat |151152**Claude Code:**153154| Bucket | Target file | When it activates |155|--------|-------------|-------------------|156| **Always-on** conventions | `CLAUDE.md` or `.claude/CLAUDE.md` | Every Claude Code session |157| **Scoped** conventions | `.claude/rules/<name>.md` with `paths` frontmatter | When Claude reads matching files |158| **Unconditional rule** | `.claude/rules/<name>.md` (no `paths`) | Every session (like always-on) |159160**Decision rule:** If a convention applies to all files in the repo, it belongs in root / always-on instructions. If it applies only to specific paths or file types, create a scoped rule.161162When targeting multiple editors, generate parallel files with equivalent content — do not duplicate guidance within a single editor's files.163164### Step 5 — Draft rule files165166Generate files using templates in `assets/`:167168**GitHub Copilot:**169- Root instructions: use `assets/copilot-instructions-template.md`170- Scoped instructions: use `assets/scoped-rule-template.md` with correct `applyTo` glob171172**Cursor:**173- Use `assets/cursor-rule-template.mdc` and set frontmatter accordingly174175**Claude Code:**176- Project instructions: use `assets/claude-rule-template.md`177- Scoped rules: place in `.claude/rules/` with `paths` frontmatter178179**Quality rules (enforced during drafting):**180181- Keep instructions concise — actionable directives, not explanations182- Use imperative voice ("Use camelCase for variables", not "Variables should use camelCase")183- Avoid duplicating guidance between root and scoped files184- Validate `applyTo` / `globs` / `paths` glob patterns match intended files185- Warn if total root instructions exceed ~80 lines (risk of context dilution)186- Warn if scoped instruction file exceeds ~50 lines (GitHub Copilot), ~500 lines (Cursor), ~200 lines (Claude Code CLAUDE.md)187- See `references/examples.md` for concrete good/bad examples188- See `assets/quality-checklist.md` for full checklist189190### Step 6 — Review and refine191192Present drafted files to the developer. For each file:1931941. Show full content1952. Highlight quality warnings (length, broad globs, duplication)1963. Ask for approval or edits197198### Step 7 — Write files199200After approval, write rule files to the repository. Create `.github/instructions/`, `.cursor/rules/`, and/or `.claude/rules/` directories as needed.201202Confirm final file list and paths before writing.203204## Expected output205206- `.github/copilot-instructions.md` — root instructions file (created or updated)207- `.github/instructions/*.instructions.md` — zero or more scoped instruction files208- `.cursor/rules/*.mdc` — zero or more Cursor rule files (when Cursor is targeted)209- `CLAUDE.md` or `.claude/CLAUDE.md` — project instructions (when Claude Code is targeted)210- `.claude/rules/*.md` — zero or more Claude Code scoped rule files211- Summary of what was created/updated and why212213## Instructions vs skills vs rules — when to use which214215| Need | GitHub Copilot | Cursor | Claude Code |216|------|---------------|--------|-------------|217| Always-on coding conventions | `copilot-instructions.md` | `.cursor/rules/*.mdc` with `alwaysApply: true` | `CLAUDE.md` |218| File/path-specific guidance | `.github/instructions/*.instructions.md` | `.cursor/rules/*.mdc` with `globs` | `.claude/rules/*.md` with `paths` |219| Task-specific multi-step workflows | A skill (`SKILL.md`) | `.cursor/rules/*.mdc` (manual or agent-selected) | Skills / subagents |220| Agent routing and orchestration | Agent definitions (`.agent.md`) | `.cursor/rules/*.mdc` with `description` | Subagent configs |221| Simple project-wide instructions | `copilot-instructions.md` | `AGENTS.md` | `CLAUDE.md` |222223Instructions and rules shape **how** the AI writes code. Skills define **what** it can do as structured tasks.224225## Safety and constraints226227Never:228229- Embed secrets, tokens, or credentials in rule files230- Generate rules that contradict repository security policies231- Overwrite existing files without showing the diff and getting approval232- Invent conventions — only document what the developer confirms233234Always:235236- Show drafts before writing any files237- Validate glob patterns against actual repository paths238- Warn on overly broad globs (e.g., `**/*` captures everything)239- Keep instructions concise and actionable240- Preserve existing content when updating (append or merge, never replace silently)241242## References243244- `references/examples.md` — concrete examples for different tech stacks245- `assets/creation-follow-up.md` — per-rule follow-up questions (purpose, exceptions, boundaries, voice)246- `assets/frontmatter-scenarios.md` — scenario-based frontmatter guide for GitHub Copilot, Cursor, and Claude Code247- `assets/copilot-instructions-template.md` — starter template for root instructions248- `assets/scoped-rule-template.md` — starter template for scoped rules249- `assets/cursor-rule-template.mdc` — starter template for Cursor rules250- `assets/claude-rule-template.md` — starter template for Claude Code rules251- `assets/quality-checklist.md` — quality review checklist