Instruction Generator

Produces clear, scoped, non-contradictory instruction files that Claude loads and follows automatically.

Instructions are always-on: they apply whenever Claude processes matching files or contexts. Keep them concise. Every word in an instruction file costs context tokens on every invocation.

Quick Decision: Which instruction file?

applyTo patterns:

• "**" — matches all files
• "**/*.ts" — TypeScript files
• "src/**" — everything under src/
• "**/*.{ts,tsx}" — multiple extensions
• Leave applyTo absent for on-demand instructions (not auto-applied)

Workflow

Follow these steps in order. Mark each ✓ when done.

Step 1 — Clarify scope

Answer before writing:

• Who is this for? All team members (workspace) or just this user (user-level)?
• What files trigger it? Language, framework, folder, or all files?
• What behavior changes? Style, safety rules, prohibited patterns, or workflow steps?

Step 2 — Choose depth

If the instruction body would exceed 60 lines, split it:

• SKILL body: overview + key rules
• Separate *.md file: extended rules, examples, edge cases

Step 3 — Write the instruction

---
applyTo: "<glob>"
description: "<optional: use for on-demand instructions>"
---

# <Short title>

<Context sentence: what this file covers and why>

## Rules

- <Rule 1: imperative, specific, verifiable>
- <Rule 2: imperative, specific, verifiable>
- <Rule n>

## Do not

- <Prohibited action 1>
- <Prohibited action 2>

See templates/instructions-concise.md and templates/instructions-extended.md.

To scaffold a stub from the command line:

python skills/instruction-generator/scripts/generate_instruction_stub.py \
  --apply-to "**/*.ts" --title "TypeScript rules" [--variant concise|extended]

Step 4 — Rewrite vague rules

Run each rule through this test: "Can Claude determine pass/fail without judgment?"

Step 5 — Check for contradictions

• Does any rule contradict another in this file?
• Does any rule contradict existing instructions in .github/copilot-instructions.md?
• Are applyTo patterns precise enough? (Overly broad patterns → high context cost)

Step 6 — Validate quality checklist

• Every rule is imperative and verifiable (no "should", "try to", "consider").
• applyTo pattern is correct glob syntax — validated against target file paths.
• No time-sensitive information (no version numbers with expiry dates, no API phases).
• Consistent terminology throughout (same term for same concept).
• Instructions don't duplicate VS Code / Copilot defaults.
• File length is appropriate for the chosen depth variant.

Run the validator to catch soft rules and frontmatter issues automatically:

python skills/instruction-generator/scripts/validate_instruction_output.py <path>
# or via poe:
poe validate-instructions <path>

Anti-patterns

• Omnibus instructions: one file covering too many unrelated concerns. Split by domain.
• Soft rules: "prefer" without a fallback condition. Use "unless X, then Y" when needed.
• Stale specifics: "until August 2025 use the old API" — becomes wrong immediately.
• Missing applyTo: without a glob, the file is on-demand only; teams expecting auto-apply will be confused.
• Duplicating documentation: instructions should tell Claude what to do, not explain the library.

Output format

Deliver the full instruction file (frontmatter + body) and note:

• Recommended file path
• Recommended scope (workspace vs user)
• Any follow-up rule files if progressive disclosure was used

See examples/ for language-specific and workflow-specific patterns. Concise template: templates/instructions-concise.md Extended template: templates/instructions-extended.md

Source: Anselmoo/universal-creator — distributed by TomeVault.