swapped docs symlink

2026-08-07 21:07:23 -05:00
parent 5005cd7001
commit f240486a7e
92 changed files with 69 additions and 42 deletions
@@ -0,0 +1,119 @@
+---
+name: copilot-customization
+description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
+---
+
+# Copilot Customization
+
+Use this skill when a task is about changing how GitHub Copilot or VS Code agents behave through customization files or MCP-backed skill resources.
+
+## When to Use
+
+- Creating or updating:
+    - `.github/copilot-instructions.md`
+    - `AGENTS.md`
+    - `CLAUDE.md`
+    - `*.instructions.md` files
+    - `*.prompt.md` files
+- Creating prompt files, custom agents, hooks, or Agent Skills.
+- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
+- Debugging why a customization is not discovered, loaded, or invoked.
+- Adding a new documentation-backed skill to this `personal-mcp` repository.
+
+## Start With The Decision
+
+Choose the smallest customization that matches the desired behavior:
+
+1. Use always-on instructions for project-wide coding standards, architecture decisions, security rules, and documentation standards that should apply to most requests.
+2. Use file-based instructions for conventions that only apply to matching files, folders, languages, frameworks, or documentation types.
+3. Use prompt files for reusable slash commands that package a single recurring prompt.
+4. Use Agent Skills for portable, task-specific workflows that may include references, scripts, examples, or templates.
+5. Use custom agents for specialized personas, tool restrictions, model choices, or role-specific workflows.
+6. Use hooks when a deterministic lifecycle action must enforce a policy, run a command, or block unsafe behavior.
+7. Use MCP servers when the agent needs live external tools, structured resources, or discoverable data beyond static instruction files.
+8. Use agent plugins when several related customizations should ship together as an installable package.
+
+If the request is ambiguous, ask only for the missing axis that changes the file type: scope, trigger, expected output, required tools, or whether it must be portable beyond VS Code.
+
+## Research Map
+
+Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
+
+## Repo Shim Pattern For Personal MCP
+
+Use a shim when you want another repository to consume this server as a preference and documentation source without duplicating methodology content.
+
+### What the shim does
+
+1. Tells the agent when to consult this MCP server.
+2. Tells the agent how to retrieve relevant guidance.
+3. Keeps repo-local behavior thin while canonical guidance stays in Personal MCP resources.
+
+### Shim formats
+
+Use either:
+
+1. A repo instruction file (`*.instructions.md`) for always-on or file-scoped behavior.
+2. A prompt file (`*.prompt.md`) for explicit, on-demand guidance retrieval.
+
+### Retrieval strategies
+
+Choose one of these patterns:
+
+1. Direct URI strategy:
+  - Read `skill://<skill-name>/SKILL.md` when the required skill is known.
+  - Read `skill://<skill-name>/_manifest` only when supporting material may be useful.
+  - Read selected supporting files at `skill://<skill-name>/<supporting-path>`.
+2. Discovery-first strategy:
+  - List resources, compare native main-resource names and descriptions, then load the best matching `SKILL.md`.
+
+### Authoring guidance for shims
+
+1. Keep shim content short and procedural; avoid copying large guidance blocks from Personal MCP.
+2. State trigger conditions clearly (for example: "when creating a new skill" or "when editing docs contracts").
+3. Specify whether to use a direct native URI or resource listing for that repo's common workflows.
+4. Prefer loading only the most relevant main file first; inspect its manifest only when needed.
+5. For stable repeated workflows, use explicit URIs. For broader or ambiguous requests, use discovery-first.
+
+### Minimal shim examples
+
+Instruction-style shim intent:
+
+1. "For markdown edits (`applyTo: '**/*.md'`), load `skill://zensical-docs/SKILL.md` and apply Zensical-native documentation conventions unless they conflict with expected MkDocs compatibility."
+
+Prompt-style shim intent:
+
+1. "For docs authoring tasks, consult `skill://zensical-docs/SKILL.md`, summarize the relevant authoring constraints, then propose the smallest markdown change for this repository."
+
+### Validation for shim implementation
+
+1. Confirm the shim triggers in expected contexts.
+2. Confirm resource loading path is unambiguous (direct URI or discovery).
+3. Confirm repo-local customization remains thin and references Personal MCP as source of truth.
+
+## Workspace Customization Workflow
+
+1. Identify the customization primitive and scope.
+2. Check existing files before creating a new one.
+3. Keep the description or frontmatter trigger specific and keyword-rich.
+4. Keep instructions concise, focused, and self-contained.
+5. Add examples only when they clarify a non-obvious convention.
+6. For `*.instructions.md`, set `applyTo` only when automatic file matching is intended.
+7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
+8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
+
+## Quality Checks
+
+Before finishing:
+
+1. Confirm the customization file is in a supported location for its intended scope.
+2. Confirm required frontmatter fields are present and valid.
+3. Confirm names match directory names where VS Code requires it.
+4. Confirm descriptions include the phrases users are likely to ask for.
+5. Confirm extra skill resources are linked from `SKILL.md`.
+6. Confirm native discovery exposes `skill://<skill-name>/SKILL.md`, `_manifest`, and supporting-file reads.
+7. State any remaining ambiguity or user choice, such as personal vs workspace scope.
+
+## Output Contract
+
+Return the concrete customization created or changed, where it lives, how to invoke or trigger it, and any validation performed.