auto generating reference front-matter

docs/frontmatter.md

@@ -76,6 +76,8 @@ x-personal-mcp:
   capabilities:
     - resource://skills/<skill-id>/document
   depends_on: []
+    # Optional: overrides and nested references only.
+    # Top-level references/*.md are auto-discovered.
   references:
     <ref-id>:
       path: references/<file>.md
@@ -93,16 +95,17 @@ Rules for `x-personal-mcp`:
 3. `tags` is optional and should be a list of kebab-case discovery labels.
 4. `capabilities` is required and lists the MCP URIs the skill publishes.
 5. `depends_on` is optional and lists other skill ids.
-6. `references` is an optional map keyed by `ref-id`.
+6. `references` is an optional map keyed by `ref-id` for overrides and nested entries.
 
 Reference entry rules:
 
 1. `ref-id` is lowercase kebab-case.
 2. `path` is a skill-relative markdown path and must stay inside the same skill directory.
-3. Nested folders under `references/` are allowed.
-4. `mime_type` defaults to `text/markdown` when omitted.
-5. `title` is an optional display label.
-6. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
+3. Top-level files under `references/*.md` are auto-discovered with `ref-id` derived from a normalized filename stem (lowercase kebab-case).
+4. Nested folders under `references/` are not auto-discovered and must be declared explicitly.
+5. `mime_type` defaults to `text/markdown` when omitted.
+6. `title` is an optional display label.
+7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.
 
 ## Validation Models
 

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
 

docs/skills/copilot-customization/SKILL.md

@@ -22,11 +22,6 @@ x-personal-mcp:
   depends_on:
     - new-skill
     - zensical-docs
-  references:
-    vscode-customization:
-      path: references/vscode-customization.md
-      mime_type: text/markdown
-      title: VS Code Customization
 ---
 
 # Copilot Customization

docs/skills/fastapi-async-sqlalchemy-modernization/SKILL.md

@@ -13,35 +13,6 @@ x-personal-mcp:
    capabilities:
       - resource://skills/fastapi-async-sqlalchemy-modernization/document
    depends_on: []
-   references:
-      index:
-         path: references/index.md
-         mime_type: text/markdown
-         title: Index
-      engine:
-         path: references/engine.md
-         mime_type: text/markdown
-         title: Engine
-      session:
-         path: references/session.md
-         mime_type: text/markdown
-         title: Session
-      transactions:
-         path: references/transactions.md
-         mime_type: text/markdown
-         title: Transactions
-      implicit-io:
-         path: references/implicit_io.md
-         mime_type: text/markdown
-         title: Implicit IO
-      observability:
-         path: references/observability.md
-         mime_type: text/markdown
-         title: Observability
-      template:
-         path: references/template.md
-         mime_type: text/markdown
-         title: Template
 ---
 
 # FastAPI Async SQLAlchemy Modernization Plan

docs/skills/fastapi-uv-docker/SKILL.md

@@ -12,23 +12,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/fastapi-uv-docker/document
   depends_on: []
-  references:
-    fastapi-best-practices:
-      path: references/fastapi-best-practices.md
-      mime_type: text/markdown
-      title: FastAPI Best Practices
-    uv-project-layout:
-      path: references/uv-project-layout.md
-      mime_type: text/markdown
-      title: uv Project Layout
-    uvicorn-settings:
-      path: references/uvicorn-settings.md
-      mime_type: text/markdown
-      title: Uvicorn Settings
-    docker-cloud-native:
-      path: references/docker-cloud-native.md
-      mime_type: text/markdown
-      title: Docker Cloud Native
 ---
 
 # FastAPI Project Best Practices

docs/skills/nicegui-ui-customization/SKILL.md

@@ -13,19 +13,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/nicegui-ui-customization/document
   depends_on: []
-  references:
-    architecture-and-styling:
-      path: references/architecture-and-styling.md
-      mime_type: text/markdown
-      title: Architecture and Styling
-    interaction-patterns:
-      path: references/interaction-patterns.md
-      mime_type: text/markdown
-      title: Interaction Patterns
-    troubleshooting-and-quality-gates:
-      path: references/troubleshooting-and-quality-gates.md
-      mime_type: text/markdown
-      title: Troubleshooting and Quality Gates
 ---
 
 # NiceGUI UI Customization Workflow

docs/skills/nicegui/SKILL.md

@@ -13,15 +13,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/nicegui/document
   depends_on: []
-  references:
-    architecture:
-      path: references/architecture.md
-      mime_type: text/markdown
-      title: Architecture
-    source-documentation:
-      path: references/source-documentation.md
-      mime_type: text/markdown
-      title: Source Documentation
 ---
 
 # NiceGUI

docs/skills/pytest-scaffolding/SKILL.md

@@ -12,19 +12,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/pytest-scaffolding/document
   depends_on: []
-  references:
-    pytest-docs:
-      path: references/pytest-docs.md
-      mime_type: text/markdown
-      title: Pytest Docs
-    fastapi-testing:
-      path: references/fastapi-testing.md
-      mime_type: text/markdown
-      title: FastAPI Testing
-    sqlalchemy-testing:
-      path: references/sqlalchemy-testing.md
-      mime_type: text/markdown
-      title: SQLAlchemy Testing
 ---
 
 # Pytest Scaffolding

docs/skills/python-logging-dictconfig/SKILL.md

@@ -12,11 +12,6 @@ x-personal-mcp:
     capabilities:
         - resource://skills/python-logging-dictconfig/document
     depends_on: []
-    references:
-        python-logging-docs:
-            path: references/python-logging-docs.md
-            mime_type: text/markdown
-            title: Python Logging Docs
 ---
 
 # Idiomatic Python Logging with dictConfig

docs/skills/vscode-configuration/SKILL.md

@@ -16,19 +16,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/vscode-configuration/document
   depends_on: []
-  references:
-    debug-launch-configurations:
-      path: references/debug-launch-configurations.md
-      mime_type: text/markdown
-      title: Debug Launch Configurations
-    fastapi-debugpy-launch:
-      path: references/fastapi-debugpy-launch.md
-      mime_type: text/markdown
-      title: FastAPI Debugpy Launch
-    tasks-json-configuration:
-      path: references/tasks-json-configuration.md
-      mime_type: text/markdown
-      title: Tasks JSON Configuration
 ---
 
 # VS Code Configuration

docs/skills/zensical-docs/SKILL.md

@@ -20,31 +20,6 @@ x-personal-mcp:
   capabilities:
     - resource://skills/zensical-docs/document
   depends_on: []
-  references:
-    index:
-      path: references/index.md
-      mime_type: text/markdown
-      title: Source Map
-    zensical-features:
-      path: references/zensical-features.md
-      mime_type: text/markdown
-      title: Feature Catalog
-    theme-customization-and-icons:
-      path: references/theme-customization-and-icons.md
-      mime_type: text/markdown
-      title: Theme Customization and Icons
-    documentation-quality:
-      path: references/documentation-quality.md
-      mime_type: text/markdown
-      title: Documentation Quality
-    discoverability-and-ia:
-      path: references/discoverability-and-ia.md
-      mime_type: text/markdown
-      title: Discoverability and IA
-    code-heavy-docs-and-mkdocstrings:
-      path: references/code-heavy-docs-and-mkdocstrings.md
-      mime_type: text/markdown
-      title: Code-Heavy Docs and Mkdocstrings
 ---
 
 # Zensical Documentation Authoring