auto generating reference front-matter

docs/new_skill.md

@@ -64,6 +64,7 @@ x-personal-mcp:
   capabilities:
     - resource://skills/<skill-id>/document
   depends_on: []
+  # Optional: only for nested references or metadata overrides.
   references:
     <ref-id>:
       path: references/<file>.md
@@ -76,7 +77,9 @@ Reference manifest rules:
 
 1. `ref-id` is lowercase kebab-case.
 2. `path` is skill-relative and must stay under `references/`.
-3. Reference paths are markdown files.
+3. Top-level `references/*.md` files are auto-discovered, and `ref-id` is derived from a normalized filename stem.
+4. Nested `references/**` markdown files must be declared explicitly.
+5. Reference paths are markdown files.
 
 No `metadata.yaml` sidecar is part of this model.
 
@@ -108,7 +111,8 @@ Compatibility rule:
 3. Populate frontmatter with `name`, `description`, and `x-personal-mcp` metadata.
 4. Ensure `x-personal-mcp.id` equals `name` and directory `<skill-id>`.
 5. Ensure `capabilities` includes `resource://skills/<skill-id>/document`.
-6. If references are exposed, declare each `ref-id` in `x-personal-mcp.references`.
+6. Add supporting docs under `references/`; top-level markdown files are exposed automatically.
+7. Declare `x-personal-mcp.references` only for nested paths or to override defaults.
 
 ## Quick Validation