started prompt mechanics

docs/skills/new-skill/SKILL.md

@@ -27,6 +27,20 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
 2. One-sentence capability statement (what it does and when to use it)
 3. Optional list of references to include under `references/`
 
+## Progressive Discovery Requirement
+
+Every new skill created from this template should be optimized for progressive discovery, so agents load only the most relevant references in the right order.
+
+Required sections for new skills:
+
+1. `When to Use` with concrete trigger conditions.
+2. `How To Use This Skill` with a short intent-first flow.
+3. `Intent Router` mapping common task intents to specific reference files.
+4. `Load Order` and `Load Budget` defaults (for example, start with one baseline reference, then one stack-specific reference).
+5. `Output Contract` requiring the references consulted and the discovery path used.
+
+If the domain includes naming or hierarchy conventions, include a dedicated naming trigger section that is consulted before structure recommendations.
+
 ## Source of Truth and Required References
 
 1. Use this file as the baseline template for new skill authoring.
@@ -47,6 +61,7 @@ docs/
     <skill-id>/
       SKILL.md
       references/
+        index.md (recommended reference router)
         ... (optional markdown files, nested folders allowed)
 ```
 
@@ -56,6 +71,7 @@ Rules:
 2. All skill-specific supporting docs live under `references/`.
 3. Skill directories are ownership boundaries; no cross-skill writes.
 4. `skill-id` is lowercase kebab-case and should remain stable.
+5. Include a progressive discovery section in `SKILL.md` that makes selective reference loading explicit.
 
 ### Framing
 
@@ -148,6 +164,9 @@ Compatibility rule:
 5. Include resource://skills/<skill-id>/document in capabilities.
 6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
 7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
+8. Add `When to Use`, `How To Use This Skill`, `Intent Router`, `Load Order`, and `Load Budget` sections in the skill body.
+9. Ensure the `Output Contract` requires reporting consulted references and the decision path.
+10. If naming conventions are part of the domain, include a naming trigger section and place naming guidance early in the flow.
 
 ## Required Outcomes
 
@@ -156,6 +175,7 @@ Compatibility rule:
 3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
 4. Keep URI and reference mapping consistent with repository conventions.
 5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
+6. Ensure the skill body is structured for progressive discovery and selective reference loading.
 
 ## Validation