prompts/docs/skills/new-skill/SKILL.md

name, description, x-personal-mcp

name	description	x-personal-mcp
new-skill	Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.	id version tags capabilities references new-skill 1.0.0 fastmcp bootstrap scaffolding skills mcp resource://skills/new-skill/document

New Skill Bootstrap

Use this skill to bootstrap a new skill in the docs-first architecture. Try to use the /create-skill where possible to structure the output, but place it alongside the other skills in this repo.

Inputs

1. New skill id (lowercase kebab-case)
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.
2. Read and follow these docs before implementing a new skill:

• docs/architecture.md
• docs/contracts/frontmatter.md
• docs/mcp_layout.md
• docs/contracts/uris.md

Canonical Skill Shape

Create one skill directory under docs/skills/:

docs/
  skills/
    <skill-id>/
      SKILL.md
      references/
        index.md (recommended reference router)
        ... (optional markdown files, nested folders allowed)

Rules:

1. SKILL.md is required.
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

Phrasing and language in the skills should reflect the intent of providing preferences and reference documentation, rather than being for a migration or transition. When a particular resource is brought in, it should focus the general way something is done.

SKILL.md Frontmatter Contract

SKILL.md frontmatter is authoritative for skill metadata.

Required top-level fields:

1. name
2. description
3. x-personal-mcp

Required x-personal-mcp fields:

1. id
2. version
3. capabilities

Optional x-personal-mcp fields:

1. tags
2. references

Canonical frontmatter template:

---
name: <skill-id>
description: <what this skill does and when to use it>

x-personal-mcp:
  id: <skill-id>
  version: 1.0.0
  tags: []
  capabilities:
    - resource://skills/<skill-id>/document
  # Optional: only for nested references or metadata overrides.
  references:
    <ref-id>:
      path: references/<file>.md
      mime_type: text/markdown
      title: <optional short title>
---

Reference manifest rules:

1. ref-id is lowercase kebab-case.
2. path is skill-relative and must stay under references/.
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.

URI Surface

Canonical resource URIs for a skill:

1. resource://skills/<skill_id>/document
2. resource://skills/<skill_id>/references/<ref_id>

Canonical discovery URIs:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}

Compatibility rule:

1. Keep URI families unversioned by default.
2. For breaking changes, update clients to the canonical replacement URIs directly.

Scope

1. Create docs under docs/skills//.
2. Define SKILL frontmatter with Anthropic and x-personal-mcp fields.
3. Treat top-level references/*.md as auto-discovered references with ref-id generated from filename.
4. Declare x-personal-mcp.references only when you need overrides or nested references/** entries.
5. Validate the docs build and MCP resource reads.

Authoring Checklist

1. Create docs/skills//SKILL.md.
2. Add docs/skills//references/ files as needed.
3. Keep skill id and directory name aligned.
4. Keep frontmatter name equal to x-personal-mcp.id.
5. Include resource://skills//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

1. Create docs/skills/<skill-id>/SKILL.md with valid frontmatter and a practical skill body.
2. Create and populate docs/skills/<skill-id>/references/ with any needed markdown references.
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

1. uv run zensical build
2. uv run pytest -q

Output Contract

Return:

1. Files created or updated
2. Validation results
3. Follow-up suggestions for improving the skill