gabrielmoreira Instruction Creator
Author instructions that pass instruction-review's five gates by construction (plus Gate 6 for always-on instructions). The gates are the quality bar; invert them, and you build to standard the first time.
Mirrors skill-creator's seven-phase structure with instruction-specific guidance. If a phase here disagrees with skill-creator on the shared scaffold, skill-creator wins; this file owns only the per-type guidance.
When to Use
- Authoring a new instruction in
.github/instructions/ - Refactoring an existing instruction (scope shift, applyTo recalibration, split, merge)
- Promoting a Mall instruction into your heir's brain
When not to use
- Authoring a skill (a procedure with steps) → use skill-creator
- Authoring a prompt (a slash-command workflow) → use prompt-creator
- Authoring an agent (a delegated sub-process role) → use agent-creator
- A one-off rule for a single file with no recurring trigger → not a brain artifact
The Seven Phases
Each phase inverts one of the five (or six) gates. Author against the phase, pass the gate.
Phase 1 — Intent capture
Answer in writing before any drafting:
- What rule does this enforce? One sentence. If it contains "and" / "+", you have two instructions — split.
- What is the trigger condition? Concrete — drives the
applyToglob in Phase 3. "When working on Azure code", "On every turn", "On files inAI-Memory/". - What does the agent do differently when this fires? Be specific. If the answer is "be more careful", the rule is too vague.
If the rule is a procedure (multi-step operation) rather than a condition-action pair, stop — author a skill, not an instruction.
Phase 2 — Prior-art scan
Select-String -Path .github/instructions/*.instructions.md -Pattern "<keyword>"
| Finding | Action |
|---|---|
| Existing instruction covers ≥70% | Extend the existing one, don't create a new file |
Adjacent instruction with different applyTo |
Check if scopes can merge under a wider applyTo |
| Mall instruction covers it | Adopt the Mall unit, retarget frontmatter |
| Nothing exists | Author from scratch — legitimate gap |
Phase 3 — Draft against Gate 1 (Spec) and calibrate applyTo
Frontmatter template:
---
description: "<third-person, what + when, ≤1024 chars>"
applyTo: "<glob pattern>"
lastReviewed: YYYY-MM-DD
---
applyTo calibration is the load-bearing decision for instructions. Too broad = token waste on every turn; too narrow = misses the cases it should catch.
| Trigger condition | applyTo shape |
Example |
|---|---|---|
| Every turn (always-on framework discipline) | ** |
act-pass, epistemic-calibration |
| Files matching a path pattern | **/path/**, **/*.ext |
markdown-mermaid (**/*.md), git-workflow (**/.*git*,**/.github/**) |
| Domain keyword in conversation | **/*keyword* |
mcp-development (**/*mcp*) |
| Specific subdirectory | **/AI-Memory/** |
cross-project-isolation, pii-memory-filter |
If applyTo: "**", the body must include an explicit always-on rationale section (Gate 6 requirement).
File location: .github/instructions/<kebab-name>.instructions.md (flat — no subfolders).
Phase 4 — Draft against Gate 2 (Quality)
| Criterion | How you author for it |
|---|---|
| Directive voice | Rules as Condition → Action tables. Imperative verbs. No narrative ("when we introduced this..."). |
| Single responsibility | One rule per file. If the title contains "and", split. |
| Rule tables over prose | Tables for the rules; prose only for rationale and anti-patterns. |
Has ## Would Revise If |
Date / count+time / observable event. Per your heir's falsifiability-deadlines discipline. |
| At least one anti-pattern table | Surfaces what the rule is not asking for. |
| ≤200 lines (pattern-applied) or ≤150 lines (always-on) | See Gate 6 for always-on. |
Phase 5 — Draft against Gate 3 (Scope)
| Target | Route |
|---|---|
| Framework-level (manifesto, tenets, claims) | Stop. Decision record, not instruction. |
| Generic across many projects | Keep in your heir baseline (Edition mirror) |
| Single project or narrow domain | That project's local-only repo |
| External-surface rule | Not an ACT instruction — author a Mall unit |
Phase 6 — Draft against Gate 4 (Safety)
Same checks as skill-creator Phase 6. Instructions rarely bundle scripts, but if they reference scripts, the script-discipline rules from skill-creator apply.
Phase 7 — Dogfood self-audit (with Gate 6 if always-on)
Before committing, run instruction-review's five gates (plus Gate 6 for always-on). Verdict lives in the commit message.
Gate 6 check — only for applyTo: "**":
- Body ≤150 lines
- Explicit "always-on rationale" prose names why this fires every turn
- No duplication of content owned by a skill
Anti-Patterns
| Anti-pattern | Correction |
|---|---|
Setting applyTo: "**" because you're unsure of the trigger |
Phase 1 forces you to name the trigger. If you can't, you don't have an instruction yet. |
| Authoring a procedure as an instruction | Procedures with steps are skills. Move it. |
| Skipping the prior-art grep | Grep is cheap; duplicate authoring is expensive. |
| Hiding the falsifier in prose | Use a ## Would Revise If heading; per your falsifiability discipline the section must be explicit. |
| Letting an always-on instruction creep past 150 lines | Always-on cost is per-turn × every-session. Cut, or narrow the applyTo. |
| Copy-pasting from a skill body into an instruction | The skill is source of truth. Cross-link. |
Falsifiability
This skill's design has failed if any of the following occur within 90 days:
- ≥2 instructions authored using this guide fail
instruction-reviewGate 1 or Gate 6 on first self-audit (phases didn't internalize the gates) - No new instructions authored via this guide in 90 days (decorative, not load-bearing — sunset)
applyTocalibration table produces consistent miscalibration (always-on chosen where pattern would do, or vice versa) ≥3 times in a quarter
Track as you would any falsified discipline (commit log, retraining notes, or curation ledger if your repo ships one) tagged [INSTRUCTION-CREATOR-MISS].
Related
- instruction-review — the five gates (+ Gate 6) this skill inverts
- skill-creator — sibling for skills; canonical seven-phase scaffold
- prompt-creator — sibling for prompts
- agent-creator — sibling for agents
- act-pass — required for medium-stakes instruction authoring