---
name: write-repo-instructions
description: Use when creating or improving repository-wide Copilot instructions, especially for monorepos, pnpm workspaces, package boundaries, build/test commands, and shared technical context.
argument-hint: "[optional repository context or specific goal]"
---------------------------------------------------------------

# Write Repo Instructions

Create or improve `.github/copilot-instructions.md`.

This skill builds concise repository-wide technical context for GitHub Copilot.

## Goal

Produce a focused `.github/copilot-instructions.md` file that tells Copilot stable, repo-wide facts and rules.

The file should help Copilot avoid wrong assumptions about the repository.

## Process

Work in three phases.

---

## Phase 1: Inspect and grill

First inspect the repository where possible.

Look for:

* `package.json`
* `pnpm-workspace.yaml`
* `turbo.json`
* `nx.json`
* `vite.config.*`
* `tsconfig*.json`
* ESLint config
* Prettier config
* test configs
* CI workflows
* package folders
* existing `.github/copilot-instructions.md`
* existing `.github/instructions/*.instructions.md`
* existing `.agents/skills/*/SKILL.md`

Then ask only essential missing questions.

Ask about:

* package manager
* workspace layout
* main technologies
* build, test, lint, typecheck, and format commands
* app/package boundaries
* shared packages
* import rules
* generated files
* legacy constraints
* ESM/CommonJS constraints
* testing expectations
* dependency-management rules
* common mistakes Copilot should avoid

Rules:

* Do not ask questions that can be answered from repository files.
* Ask concise grouped questions.
* Stop asking when enough context exists.
* Prefer concrete repository facts over generic preferences.

---

## Phase 2: Deslop the context

Compress all gathered information into a short technical brief.

Keep only:

* stable repo-wide facts
* commands Copilot should use
* architectural boundaries
* dependency rules
* testing expectations
* files Copilot should avoid editing
* recurring mistakes to prevent

Remove:

* vague advice
* motivational language
* generic engineering principles
* duplicated rules
* temporary details
* package-specific details
* task-specific workflows

Classify every important detail into one bucket:

1. Include in `.github/copilot-instructions.md`
2. Move to `.github/instructions/*.instructions.md`
3. Move to `.agents/skills/*/SKILL.md`
4. Exclude

Show this classification before writing the final file.

---

## Phase 3: Write `.github/copilot-instructions.md`

Generate the final file.

Requirements:

* Keep it concise.
* Use markdown.
* Use direct instructions.
* Prefer concrete commands.
* Avoid generic advice.
* Avoid long explanations.
* Include only repo-wide guidance.
* Do not duplicate package-level instructions.
* Do not include task workflows that belong in skills.

Recommended structure:

```md
# Repository instructions

## Repository overview

## Package manager and workspace

## Common commands

## Architecture and package boundaries

## Coding conventions

## Testing expectations

## Dependency rules

## Files Copilot should not edit

## Common mistakes to avoid

## Related package instructions and skills
```

## Output format

Return:

1. Proposed `.github/copilot-instructions.md`
2. Suggested package-level instruction files
3. Suggested task skills
4. Missing information that should be filled manually

## Rules

* If the repository already has instructions, improve them instead of replacing blindly.
* If some facts are uncertain, mark them as `TODO`.
* Do not invent commands.
* Do not invent package names.
* Do not include package-specific rules in the repo-wide file unless they affect the whole repository.
* Keep the final instructions short enough to remain useful in every Copilot task.