# Kit Copilot Create Core Instruction > Creates the foundational .github/copilot-instructions.md file that provides universal project context for all GitHub Copilot interactions. Use when user asks to create, generate, set up, or scaffold copilot instructions, core instructions, project instructions, or copilot-instructions.md. - Skill: `tomevault-io/kit-copilot-create-core-instruction` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/kit-copilot-create-core-instruction` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kit-copilot-create-core-instruction/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - 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/kit-copilot-create-core-instruction --- # Create Core Copilot Instruction ## What This Skill Does Creates a production-ready `.github/copilot-instructions.md` file — the foundational layer of GitHub Copilot's custom instructions system. This file is attached to **every** Copilot conversation, providing universal project context that shapes all AI interactions. ## Key Concepts: The Layered Instruction Architecture GitHub Copilot supports a layered approach to custom instructions: | Layer | File | Scope | Purpose | |-------|------|-------|---------| | **Core** | `.github/copilot-instructions.md` | Every conversation | Universal project context | | **Granular** | `.github/instructions/*.instructions.md` | Matching files only (via `applyTo` glob) | File-type-specific or folder-specific conventions | This skill creates the **core layer**. The core file must contain only what Copilot needs to know universally — regardless of which file or feature is being worked on. File-type-specific or folder-specific conventions belong in granular instruction files. ### The Golden Rule > **The core file is attached to every single Copilot conversation. Every line must earn its place.** ## Content Boundaries Knowing what belongs in the core file — and what doesn't — is critical for quality. | Include in Core File | Exclude (Delegate or Omit) | |----------------------|----------------------------| | Project type and domain context | File-type-specific conventions (→ granular `.instructions.md` files) | | Tech stack with versions (brief) | Standard language/framework behaviors | | Universal naming conventions | Verbose API references | | Architectural philosophy | Folder-specific patterns (→ granular `.instructions.md` files) | | Cross-cutting patterns (errors, logging) | Library documentation | | Common pitfalls/anti-patterns | Detailed configuration examples | | Key workflow commands (essential only) | Exhaustive command lists | | Testing philosophy (not test file specifics) | Test file structure details (→ granular files) | **Never include instructions about:** - How to create custom Copilot prompts, agents, skills, or instruction files - Meta-guidance about Copilot customization itself The core instruction file must be **about the project's code and conventions**, not about Copilot tooling. ## Step-by-step Procedure ### Step 1: Check for Existing File Before starting, check if `.github/copilot-instructions.md` already exists in the workspace. - **If it exists**: Read the current contents. Ask the user whether they want to replace it entirely or update/improve it. If updating, identify what's missing or outdated before proceeding. - **If it doesn't exist**: Proceed to Step 2. Also check for related files that inform the core instructions: - `.github/instructions/*.instructions.md` — understand what granular instructions already exist so the core file doesn't duplicate them - `AGENTS.md`, `CLAUDE.md` — alternative instruction formats that may contain relevant conventions ### Step 2: Discovery Perform systematic discovery to identify what belongs in the universal context layer. For each phase, search the workspace for the listed files and patterns. #### Phase 1: Project Identity Establish the fundamental nature of the project: - **Project type**: Web app, API, library, CLI tool, monorepo, microservice? - **Domain**: E-commerce, fintech, healthcare, developer tools, etc.? - **Stage**: Greenfield, mature, legacy modernization? **Check**: `README.md`, `CONTRIBUTING.md`, project root for clues. #### Phase 2: Technology Stack Inventory Scan for authoritative technology sources and extract versions: - **Package manifests**: `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `*.csproj`, `Gemfile`, `pyproject.toml`, `composer.json` - **Config files**: `tsconfig.json`, `vite.config.*`, `next.config.*`, `astro.config.*`, `webpack.config.*`, `.babelrc`, `Dockerfile` - **Document only major technologies with versions** (e.g., "Next.js 14, TypeScript 5.4, Prisma 5.x") #### Phase 3: Universal Conventions Mining Identify conventions that apply across the entire codebase: - **Linter/formatter configs**: `.eslintrc.*`, `eslint.config.*`, `biome.json`, `.prettierrc.*`, `ruff.toml`, `.golangci.yml`, `.editorconfig` - **Existing documentation**: `README.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`, `docs/` directory, ADRs (Architecture Decision Records) - **Cross-cutting patterns**: Error handling, logging, authentication approaches, API response formats #### Phase 4: Architecture Overview Map the high-level structure without going into file-level detail: - **Folder structure philosophy**: Feature-based, layer-based, domain-driven? - **Key architectural patterns**: Clean architecture, hexagonal, MVC, CQRS, etc.? - **Monorepo structure** (if applicable): What packages exist and their relationships? **Check**: Top-level directories, `turbo.json`, `nx.json`, `lerna.json`, `pnpm-workspace.yaml`. **If critical information is missing after scanning**: Ask the user targeted questions to clarify uncertainties rather than making assumptions. For example, if the project has no README and the domain isn't obvious from code, ask. #### Phase 5: Delegation Analysis Determine what should NOT be in the core file — this is as important as what goes in. Apply **The "Every File" Test** to each potential instruction: > "Does this apply when working on ANY file in the project?" > - **Yes** → Include in core file > - **No** → Delegate to a granular `.instructions.md` file or omit When you find conventions that are file-type-specific or folder-specific, note them as candidates for granular instruction files. Inform the user about these candidates after creating the core file. ### Step 3: Draft Using the discovery results, compose the core instruction file: 1. **Use the bundled template** — Start from the [instruction-template.md](./instruction-template.md) as a structural foundation. 2. **Apply Convention Triangulation** — Validate conventions by cross-checking multiple sources: - Actual code patterns across different areas - Linter/formatter configurations - Existing documentation - Git history (what patterns are consistently followed?) 3. **Detect Greenfield vs Established**: - **Established project**: Mine conventions from existing code; document what IS, not what should be - **Greenfield project**: Suggest best practices for the stack; explicitly note these are recommendations 4. **Be concise** — Aim for **50-150 lines maximum**. Every line must earn its place. 5. **Structure for scanning** — Use clear headings, bullet points, and concise statements. 6. **Prioritize information** — Put the most important context (tech stack, architecture) first. Present the complete draft to the user for review before generating. ### Step 4: Generate Once the user confirms: 1. **Create the directory** `.github/` if it doesn't exist. 2. **Write the file** to `.github/copilot-instructions.md`. 3. Do NOT output the file content as a code block in chat — create the actual file. ### Step 5: Validate Before reporting completion, verify: - [ ] File is located at `.github/copilot-instructions.md` - [ ] Content is within the 50-150 line target range - [ ] Every instruction passes The "Every File" Test (universal applicability) - [ ] No file-type-specific conventions are included (those belong in granular files) - [ ] No Copilot meta-guidance (how to use prompts, agents, skills, etc.) - [ ] No generic AI advice ("write clean code", "follow best practices") - [ ] No library API documentation (Copilot already knows these) - [ ] Tech stack versions are documented - [ ] Architecture overview is present but concise **After validation, inform the user about:** 1. **Granular instruction candidates** — Any file-type-specific or folder-specific conventions discovered during Phase 5 that should become `.github/instructions/*.instructions.md` files. 2. **Next steps** — Suggest creating granular instruction files for the identified candidates to complete the instruction architecture. ## Key Rules - **Conciseness is non-negotiable** — The core file is attached to every conversation. Bloated instructions waste context window and degrade Copilot's performance. - **Universal applicability** — Every line must pass The "Every File" Test. If it doesn't apply universally, it doesn't belong. - **Discovery before drafting** — Never skip the discovery phases. Assumptions lead to incorrect or incomplete instructions. - **Always create the file** — Write to `.github/copilot-instructions.md` directly. Never output instructions inline in chat as the final deliverable. - **Respect existing granular files** — If `.github/instructions/` already has granular files, don't duplicate their content in the core file. - **Document what IS, not what should be** — For established projects, capture actual conventions from the codebase, not aspirational ideals. --- > Source: [ikcode-dev/copilot-kit](https://github.com/ikcode-dev/copilot-kit) — distributed by [TomeVault](https://tomevault.io).