docs: add write-skill skill

.agents/skills/write-skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: write-skill
+description: Use when creating, updating, or reviewing agent skills
+---
+
+# Write Skill
+
+- Use this skill when creating, updating, or reviewing skill files
+- When authoring a skill, include in its description when it should and should not be used
+- Keep agent skills short and concise
+- Keep skill prose under 200 lines, excluding reference tables; move additional guidance into references
+- Use a `references` sub-folder in a skill when it becomes too long or needs to link out to different topics
+- Links to references must be kept up-to-date as files are created, updated, or removed
+- References must include a table of contents as the first section
+- Each entry in the table of contents should include the section heading's line number in the reference file so agents can make targeted reads
+- After creating or editing a reference, update its table of contents and verify every entry's line number against the section heading in the final formatted file
+- If using a references folder, `SKILL.md` must include:
+  - A references section
+  - A table in this section that provides a name/link to the reference and a description for when to use it
+- Use the references table to select files relevant to the current task; do not load all references by default
+- Read each selected reference's table of contents first, then use its line numbers to read only the relevant sections
+- Read additional sections or linked references only when needed to complete the task
+- If line numbers are stale, locate the section by its heading
+- Avoid duplicating information across references, instead consolidate or extract out information
+- Always report contradictions in references and recommend a resolution. Obtain permission before modifying files to resolve them
+- Write descriptions that identify the specific tasks that should trigger the skill. Avoid broad wording that causes it to load for unrelated work
+
+## Examples
+
+### SKILL.md
+
+```md
+---
+name: skill-name
+description: Information about the skill, when to use it, and how to use it
+---
+
+# Skill name
+
+<!-- An overview of the skill -->
+
+## References
+
+| Name | Description |
+| :--- | :---------- |
+| [Reference](./references/reference.md) | A brief description of the reference and when to use it |
+```
+
+### .agents/skills/<skill>/references/<reference>.md
+
+```md
+# Reference
+
+Brief overview of the reference
+
+## Table of Contents
+
+- [Example](#example), L:11
+
+<!-- ... -->
+
+## Example
+```

.github/copilot-instructions.md

@@ -2,6 +2,12 @@
 
 **ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
 
+## User feedback on skills
+
+- When a user explicitly corrects guidance from an active skill or requests a conflicting approach, point out the difference and ask whether it is a one-off exception or a lasting change
+- If it is a lasting change, propose a specific update to the relevant skill or reference and obtain permission before editing
+- Do not infer permanent guidance from a single action or exception
+
 ## Repository Organization
 
 The project is the React implementation of GitHub's Primer Design System authored as a monorepo with separate npm workspaces.

.gitignore

@@ -14,9 +14,6 @@ css/
 # Dependencies
 node_modules
 
-# Local agent workspaces
-.agents
-
 # Gatsby
 public/