zensical docs skill

docs/new_skill.md

@@ -14,7 +14,9 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
    Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
 
 4. Expose the document resource in `server.py`.
-   Follow the existing pattern: create a `FastMCP` instance, register `resource://skills/<skill-id>/document`, and return `load_skill_document(skill_id=<skill-id>, skill_slug=<slug>)`.
+   Follow the existing pattern: create a `FastMCP` instance, register `resource://skills/<skill-id>/document`, and return the shared loader result.
+   For the default layout, load `docs/skills/<slug>/SKILL.md`.
+   For special cases, set `document_path` in `metadata.yaml` to a repo-relative Markdown file and load from metadata instead of hardcoding a path in the server.
 
 5. Register the catalog metadata.
    In `metadata.yaml`, add the skill `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`. The `capabilities` list should include `resource://skills/<skill-id>/document`.
@@ -23,7 +25,7 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
    Import the new server in `src/personal_mcp/mcp.py` and add an `mcp.mount(...)` call with the Python namespace.
 
 7. Let the loader and catalog do the rest.
-   The document loader reads canonical Markdown from `docs/skills/<slug>/SKILL.md`, and the catalog discovers metadata from `src/personal_mcp/skills/*/metadata.yaml` automatically.
+   The document loader reads canonical Markdown from `docs/skills/<slug>/SKILL.md` by default, or from `metadata.yaml`'s optional `document_path` override when present. The catalog discovers metadata from `src/personal_mcp/skills/*/metadata.yaml` automatically.
 
 8. Rebuild and smoke-test.
    Run `uv run zensical build` to publish the docs site, then run a quick Python check or start the app to confirm the new resource loads.
@@ -39,8 +41,9 @@ To keep behavior consistent across MCP clients and Copilot session types, follow
 ### Do
 
 1. Add or update `metadata.yaml` fields (`id`, `description`, `tags`, `capabilities`) so catalog discovery quality stays high.
-2. Use catalog resources as the primary discovery surface.
-3. Add thin, read-only catalog tools only when client behavior needs a fallback path.
+2. Use `document_path` when a skill should expose a Markdown file outside `docs/skills/<slug>/SKILL.md`.
+3. Use catalog resources as the primary discovery surface.
+4. Add thin, read-only catalog tools only when client behavior needs a fallback path.
 
 ### Don't
 
@@ -92,11 +95,14 @@ description: <One sentence describing what the skill provides.>
 tags:
   - <tag-one>
   - <tag-two>
+document_path: <optional repo-relative path to a markdown file>
 capabilities:
   - resource://skills/<skill-id>/document
 depends_on: []
 ```
 
+Omit `document_path` when the canonical document is `docs/skills/<slug>/SKILL.md`.
+
 ## Root Mount Template
 
 Add an import in `src/personal_mcp/mcp.py`:

docs/skills/zensical-docs/SKILL.md

@@ -33,6 +33,16 @@ Always start a new documentation project with `uv run zensical new`.
 - This command provides the baseline scaffolding you need for structure, configuration, and theme setup.
 - Do not hand-build a new project skeleton when this command is available.
 
+## Related Skill Discovery
+
+When the task is not just writing docs but creating or wiring a new MCP skill in this repository, use catalog discovery to load the bootstrap skill before drafting implementation steps.
+
+1. Search the catalog with terms such as `new skill`, `skill bootstrap`, or `scaffold skill`.
+2. Fetch the `new-skill` document through the catalog tool path.
+3. Use that skill for runtime package, metadata, and mount wiring, then return here for documentation architecture and Zensical-specific authoring guidance.
+
+This keeps implementation guidance and documentation guidance separated while still making both discoverable from one request.
+
 ## Inputs To Collect
 
 Collect these before writing. If missing, make explicit assumptions.

docs/usage.md

@@ -147,6 +147,50 @@ Weak metadata reduces Copilot match quality and increases wrong context injectio
 
 If you skip the catalog/index step, behavior is less predictable and may either miss relevant skills or pull too much context.
 
+## 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 catalog tools instead.
+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` or `resource://catalog/patterns`
+2. `resource://skills/<skill-id>/document`
+
+Preferred tool fallback order:
+
+1. `search_patterns`
+2. `get_pattern_by_id`
+3. `get_skill_document_by_id`
+
+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: