---
name: fusion-rule-author
description: '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.'
license: MIT
metadata:
  version: "0.1.1"
  status: active
  owner: "@equinor/fusion-core"
  role: support
  tags:
    - copilot
    - cursor
    - claude-code
    - rules
    - developer-experience
    - onboarding
    - repository-setup
    - system
---

# 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

- [ ] Repository context (working directory or repo URL)

### Gathered during interview

- [ ] Tech stack (languages, frameworks, build tools)
- [ ] Code conventions (naming, formatting, patterns)
- [ ] Testing expectations (framework, coverage, style)
- [ ] Documentation preferences (comments, TSDoc/JSDoc, README standards)
- [ ] Commit and PR conventions
- [ ] Error handling patterns
- [ ] Security or compliance constraints
- [ ] File/path-specific conventions that need scoped rules

## 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:**
1. Concrete conventions that can become imperative directives
2. Build/test/lint commands the AI should know
3. Architecture boundaries or patterns to follow
4. 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:

1. **Tech stack** — languages, frameworks, runtime, package manager
2. **Code style** — naming conventions, formatting rules, import ordering
3. **Architecture** — project structure, key patterns (MVC, hexagonal, etc.)
4. **Testing** — framework, conventions, coverage expectations
5. **Documentation** — inline comments style, doc generation, README standards
6. **Git workflow** — branch naming, commit message format, PR expectations
7. **Security** — sensitive data handling, auth patterns, compliance rules
8. **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:

1. Show full content
2. Highlight quality warnings (length, broad globs, duplication)
3. 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