usage docs

docs/new_skill.md

@@ -28,6 +28,26 @@ Use this checklist after generating a new skill under `docs/skills/<slug>/`.
 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.
 
+## Discovery Tool Policy
+
+To keep behavior consistent across MCP clients and Copilot session types, follow this boundary:
+
+1. Keep per-skill servers resource-only.
+2. Keep discovery/query tools centralized in the catalog server.
+3. Keep canonical content in `docs/skills/<slug>/SKILL.md` and expose it through `resource://skills/<skill-id>/document`.
+
+### 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.
+
+### Don't
+
+1. Do not add duplicate discovery tools to each skill package.
+2. Do not duplicate canonical skill guidance in tool descriptions.
+3. Do not create mutating catalog tools for skill discovery.
+
 ## Minimal Shape
 
 - Docs content: `docs/skills/<slug>/SKILL.md`