diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..5c95047b
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,42 @@
+# Copilot instructions
+
+Read `AGENTS.md` first. It is the authoritative repository contract. Then use
+`docs/SKILL.md` to load only the skill that matches the task.
+
+## Project shape
+
+This is a Docusaurus site. User-facing docs and blog pages are built with
+React components under `src/`; build-time fetchers under `scripts/` populate
+data consumed by dashboard and catalog components. Do not hand-edit generated
+data under `static/data/`.
+
+## Live pages and audits
+
+- Audit an externally visible page from the live, cache-busted route and the
+  matching `origin/main` source. A local branch or tracked seed is not
+  evidence of the deployed state.
+- For standalone docs UI, use `src/css/custom.css`, Infima variables, and
+  established local components as the visual source of truth. Keep styling for
+  external services isolated; it must not reshape the documentation site.
+- If a task asks for a live, deployed, shipped, or merged result, completion
+  requires the merge to `main`, a successful Pages deployment, and a
+  cache-busted request to the requested route. A local commit, branch, or open
+  pull request is not completion.
+
+## Worktrees and validation
+
+- Use a linked worktree for changes when the main checkout is not already
+  isolated. In a new worktree, run `npm install --legacy-peer-deps` before
+  broad checks: release-card tests resolve assets from that worktree's own
+  `node_modules`.
+- Use focused `node --test scripts/<name>.test.js` checks during development.
+  Run `just check` before every commit. Use `npm run build:ci` to validate a
+  build without refetching remote data.
+
+## Learning capture
+
+- Every completed engineering task updates the smallest relevant
+  `docs/skills/` procedure when it yields a reusable lesson. If the lesson
+  changes how an agent investigates, validates, designs, or ships work, update
+  the applicable agent instructions in the same change. Neither update
+  substitutes for the other.
diff --git a/docs/skills/skill-improvement.md b/docs/skills/skill-improvement.md
index 4abd9274..c4485088 100644
--- a/docs/skills/skill-improvement.md
+++ b/docs/skills/skill-improvement.md
@@ -40,8 +40,11 @@ that, every session starts from zero.
 1. Ship the requested work and verify it.
 2. Extract one reusable, non-obvious lesson from the work.
 3. Put that lesson in the smallest relevant `docs/skills/` file.
-4. Commit the skill update with the work in the same pull request.
-5. Re-read the skill as a new agent and remove status reports, dates, and
+4. Update the applicable agent instruction file when the lesson changes how an
+   agent must investigate, validate, design, or ship work.
+5. Commit the skill and agent-instruction updates with the work in the same
+   pull request.
+6. Re-read the skill as a new agent and remove status reports, dates, and
    resolved issue lists.
 
 ## The two-output rule
@@ -49,10 +52,12 @@ that, every session starts from zero.
 Every session produces two outputs:
 
 1. **The work** — the PR, fix, or feature.
-2. **The learning** — what a future agent needs to know.
+2. **The learning** — what a future agent needs to know, in the relevant skill
+   and, when applicable, agent instructions.
 
 Output 1 without output 2 means the factory did not improve. The learning goes
-in `docs/skills/`, in the **same pull request**, never a follow-up.
+in `docs/skills/` and any applicable agent instructions, in the **same pull
+request**, never a follow-up.
 
 ## What earns a skill file
 
@@ -142,7 +147,8 @@ agent. That is the bar.
 
 ## Red Flags
 
-- The session ends with implementation changes but no skill update.
+- The session ends with implementation changes but no skill and agent
+  instruction updates when the lesson applies to both.
 - A skill contains dates, resolved work items, live status, or a running
   backlog.
 - The learning is a summary of changed files rather than an operating rule.