# J03fr0st Maestro Writing Instructions > Writing Instruction Files - Skill: `tomevault-io/j03fr0st-maestro-writing-instructions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/j03fr0st-maestro-writing-instructions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/j03fr0st-maestro-writing-instructions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/j03fr0st-maestro-writing-instructions --- # Writing Instruction Files Create `.instructions.md` files in `.github/instructions/` that automatically apply guidelines when matching files are edited. Instruction files let teams enforce conventions consistently without relying on memory or code review alone. ## File Types | Type | Location | Scope | |------|----------|-------| | `copilot-instructions.md` | `.github/` root | All chat requests — use for project-wide standards | | `*.instructions.md` | `.github/instructions/` | Files matching `applyTo` glob — use for language or domain-specific rules | | `AGENTS.md` | Workspace root | Multi-agent workflows | ## File Format Every instruction file needs YAML frontmatter followed by Markdown content: ```markdown --- applyTo: "**/*.ts" description: TypeScript coding standards name: TypeScript Guidelines --- # TypeScript Guidelines - Use `interface` over `type` for object shapes — interfaces produce clearer error messages and support declaration merging. - Prefer `unknown` over `any` — this forces explicit type narrowing and catches bugs at compile time. - Export types from the same file as their implementation — keeps imports simple and avoids circular dependencies. ``` ## Frontmatter Fields | Field | Purpose | |-------|---------| | `applyTo` | Glob pattern that determines when this file is automatically included. Omit for manual-only inclusion. | | `description` | Short description shown in the Copilot UI to help users understand what this file covers. | | `name` | Display name in the UI (defaults to the filename if omitted). | ## Common Glob Patterns | Pattern | Matches | |---------|---------| | `**` | All files | | `**/*.ts` | All TypeScript files | | `**/*.component.ts` | Angular components | | `src/**` | All files in src/ | | `**/*.{js,ts}` | JS and TS files | | `**/tests/**` | All test files | | `**/*.{css,scss}` | Stylesheets | ## Body Content - Write in natural language using Markdown. - Keep instructions short, concise, and actionable — Copilot processes these on every matching file edit, so brevity reduces noise. - Use bullet points over paragraphs — they are easier to scan and less likely to contain contradictions. - Reference files with relative links: `[config](../path/to/file.json)` — this gives Copilot direct access to referenced content. - Reference tools inline: `#tool:`. ## Rules - **One file per topic or language** — splitting by concern makes each file easier to maintain and prevents unrelated rules from coupling together. - **Use specific glob patterns** — overly broad `applyTo` (like `**`) applies your rules to every file, which adds noise and can cause conflicting guidance across instruction files. - **Do not duplicate instructions across files** — duplication leads to drift when one copy is updated but not the other. Reference shared rules from a single source instead. - **Do not include secrets or credentials** — instruction files are version controlled and visible to all collaborators. - **Store project-specific instructions in the workspace** — this ensures they travel with the repo and stay version controlled. - **Reference other instruction files in prompts** — if a prompt needs the same guidelines, link to the instruction file rather than copying its content. ## Conflict Resolution and Precedence When multiple instruction files match the same file, Copilot merges them. Handle conflicts by: 1. **More specific globs win** — `**/*.component.ts` is more targeted than `**/*.ts`. Put specific overrides in the narrower file. 2. **Do not contradict across files** — if two files disagree, Copilot has no guaranteed precedence. Resolve conflicts by consolidating the rules into one file or splitting the globs so they do not overlap. 3. **Project-level (`copilot-instructions.md`) sets defaults** — use it for universal standards. Use scoped instruction files for language or domain-specific overrides. ## Complete Example A real-world instruction file for a React project: ```markdown --- applyTo: "**/*.tsx" description: React component conventions for the design system name: React Components --- # React Component Standards ## Structure - One component per file. Name the file to match the default export. - Place components in `src/components//` with an `index.ts` barrel export. ## Props - Define props as an interface named `Props`. - Destructure props in the function signature, not in the body. - Provide JSDoc comments for non-obvious props. ## Styling - Use CSS Modules (`*.module.css`). Do not use inline styles except for truly dynamic values (e.g., calculated positions). - Follow the design token system in [tokens](../src/styles/tokens.ts). ## Testing - Co-locate test files as `.test.tsx`. - Test user-visible behavior, not implementation details. ``` ## Related Skills See the **writing-prompts** skill for creating reusable `/` commands that can reference instruction files. --- > Source: [J03Fr0st/maestro](https://github.com/J03Fr0st/maestro) — distributed by [TomeVault](https://tomevault.io).