john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
John Lancaster
2026-06-22 08:39:18 -05:00
parent 313c4ecb1e
commit 1cfe9c8e40
2 changed files with 139 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/authoring.md
+74 -1
View File
@@ -89,7 +89,78 @@ Source examples:
- [FastMCP docs](https://gofastmcp.com/getting-started/welcome)
- [Zensical docs](https://zensical.org/docs/)
## Navigation And Frontmatter
## Authoring for GitHub Copilot
For resource selection or tool-based matching to work well, each skill should have:
1. precise `description`
2. focused `tags`
3. explicit `capabilities`
4. stable `id` and slug naming
Weak metadata reduces Copilot match quality and increases wrong context injection.
### Copilot Instruction Authoring Pattern
If you want Copilot to use `personal-mcp` skill content more reliably, instruction files should describe three things clearly:
1. when MCP-backed skill guidance is relevant
2. which retrieval path Copilot should prefer first
3. how much skill context it should load before answering
Instructions strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. Keep wording explicit about preferred path and fallback path.
Repository policy:
1. start from catalog discovery
2. prefer MCP resources when the current chat surface exposes resource attachment
3. fall back to catalog tools when resource attachment is unavailable
4. keep loaded skill context bounded
Suggested instruction text:
```md
When a task may match a documented implementation pattern from `personal-mcp`:
1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
4. Load only the most relevant skill document, or at most 2 skill documents.
5. Reconcile loaded skill guidance with the actual repository code before making changes.
Preferred resource order:
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed
Preferred tool fallback order:
1. `list_resources`
2. `read_resource`
3. `search_patterns`
4. `get_pattern_by_id`
5. `get_skill_document_by_id`
Compatibility aliases for clients that use `catalog_*` naming are also available:
1. `catalog_search_patterns`
2. `catalog_get_pattern_by_id`
3. `catalog_get_skill_document_by_id`
4. `catalog_search_prompts`
5. `catalog_get_prompt_by_id`
Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
If confidence is low after discovery, ask one clarifying question before loading more context.
```
This is guidance, not a guarantee. It defines a reliable policy while preserving the resource-first architecture.
Thin shim path binding guidance for MCP consumers is covered in [Skill Usage Mechanics](./usage.md).
## Zensical Details
When adding or restructuring pages:
@@ -116,6 +187,8 @@ uv run ty check
uv run pytest
```
Address any errors or warnings that result.
If a change only affects docs content, `uv run zensical build` is still required.
## Quick Authoring Checklist
docs/usage.md
+65 -79
View File
@@ -138,16 +138,9 @@ flowchart TD
H --> I
```
## Authoring Requirements For Reliable Matching
## Authoring Requirements
For resource selection or tool-based matching to work well, each skill should have:
1. precise `description`
2. focused `tags`
3. explicit `capabilities`
4. stable `id` and slug naming
Weak metadata reduces Copilot match quality and increases wrong context injection.
Authoring rules for metadata quality and instruction patterns are maintained in [Authoring Guide](./authoring.md).
## Practical Guidelines
@@ -175,64 +168,6 @@ Behavior:
2. `bm25` uses ranked natural-language matching.
3. `list_resources` and `read_resource` stay visible so resource-backed fallback remains primary.
## Copilot Instruction Pattern
If you want Copilot to use `personal-mcp` skill content more reliably, the instruction file should describe three things clearly:
1. when MCP-backed skill guidance is relevant
2. which retrieval path Copilot should prefer first
3. how much skill context it should load before answering
That matters because instructions can strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. A good instruction tells Copilot to prefer the canonical MCP content path while remaining accurate about the fallback path.
In this repository, the right policy is:
1. start from catalog discovery
2. prefer MCP resources when the current chat surface exposes resource attachment
3. fall back to catalog tools when resource attachment is unavailable
4. keep loaded skill context bounded
Suggested instruction text:
```md
When a task may match a documented implementation pattern from `personal-mcp`:
1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
4. Load only the most relevant skill document, or at most 2 skill documents.
5. Reconcile loaded skill guidance with the actual repository code before making changes.
Preferred resource order:
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/<skill-id>/document`
4. `resource://skills/<skill-id>/references/<ref-id>` when needed
Preferred tool fallback order:
1. `list_resources`
2. `read_resource`
3. `search_patterns`
4. `get_pattern_by_id`
5. `get_skill_document_by_id`
Compatibility aliases for clients that use `catalog_*` naming are also available:
1. `catalog_search_patterns`
2. `catalog_get_pattern_by_id`
3. `catalog_get_skill_document_by_id`
4. `catalog_search_prompts`
5. `catalog_get_prompt_by_id`
Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
If confidence is low after discovery, ask one clarifying question before loading more context.
```
This is intentionally guidance, not a guarantee. It gives Copilot a strong policy for when to use resources and when to fall back to discovery tools, while preserving the resource-first architecture.
## Failure Modes and Recovery
Common failure modes:
@@ -258,22 +193,13 @@ Use this checklist when configuring GitHub Copilot in VS Code against `personal-
2. verify catalog resources are readable
3. verify at least one `resource://skills/<id>/document` can be fetched
4. add one deterministic `/` command for fallback
5. add Copilot instruction: prefer catalog-first discovery, then targeted skill fetch
5. confirm your workspace instruction policy exists (see [Authoring Guide](./authoring.md))
6. verify context size remains bounded
7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each
## Local Ruff Workflow
## Runtime Discovery Workflow
Use [Ruff](https://docs.astral.sh/ruff/) locally through `uv` so lint and format checks are consistent for contributors.
1. Lint check: `uv run ruff check .`
2. Apply safe lint fixes: `uv run ruff check . --fix`
3. Format files: `uv run ruff format .`
4. Format check (CI-style): `uv run ruff format --check .`
Rule-family baseline for this repository is `E`, `F`, `I`, and `UP`, configured in [pyproject.toml](../pyproject.toml).
Suggested instruction policy text:
Use this runtime sequence in chat sessions:
1. Start with catalog-first discovery.
2. Prefer MCP resources when the chat surface exposes resource attachment.
@@ -281,6 +207,66 @@ Suggested instruction policy text:
4. Prefer `list_resources`/`read_resource` first when operating in tool-only clients.
5. If confidence is low, ask one clarifying question before loading more.
## Thin Shim Path Binding Pattern
For repositories that consume this MCP server, thin shims are a usage pattern for binding path scopes to the right MCP resources. The "thin shims" are just lightweight, repo-specific instructions files that tell Copilot to use certain MCP resources when editing files that match a pattern. That helps with ensuring Copilot uses the intended resources without too much specific goading in the prompt.
Use thin shims in Copilot instruction files to bind file-path scopes to:
1. the most relevant docs page for human-readable conventions
2. the matching MCP resource URI for machine retrieval
Keep each shim short: trigger, primary resource, minimal execution pattern, and one fallback rule.
Recommended binding pattern:
1. Put shims in `.github/instructions/*.instructions.md`.
2. Scope each shim with `applyTo` so it activates only where needed.
3. Point to one primary `resource://skills/<skill-id>/document` URI.
4. Link one repository docs page as the human-facing companion.
5. Expand to references only when the task needs deeper detail.
Current repository examples:
| applyTo scope | Primary docs page | Primary MCP resource |
| --- | --- | --- |
| `**/*.md` | [docs/authoring.md](./authoring.md) | `resource://skills/zensical-docs/document` |
| `tests/**` | [docs/testing.md](./testing.md) | `resource://skills/pytesting/document` |
| `.vscode/**` | [docs/skills/vscode-configuration/SKILL.md](./skills/vscode-configuration/SKILL.md) | `resource://skills/vscode-configuration/document` |
Minimal shim shape:
```md
---
name: <short scope name>
description: Route <path scope> edits to the Personal MCP <skill-id> resource.
applyTo: '<glob>'
---
When editing files matching <glob>, use `resource://skills/<skill-id>/document` as the primary guidance source.
Execution pattern:
1. Load the primary skill document first.
2. Apply only sections relevant to the file being edited.
3. Keep edits minimal and aligned with repository conventions.
4. If confidence is low, ask one clarifying question before editing.
Companion docs page: [docs/<page>.md](./<page>.md)
```
When to use thin shims:
1. Repositories that want thin local policy while keeping canonical guidance in MCP resources.
2. Stable, repeated workflows with clear path ownership.
3. Cases where teams need predictable retrieval behavior.
When not to use thin shims:
1. Broad, ambiguous tasks with unclear ownership boundaries.
2. Cases where one shim would need many exceptions.
3. Situations better handled by catalog-first discovery at runtime.
## Summary
The intended model is: