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

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
new-skill	Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.	What skill are you creating, and what problem should it solve?	id version tags capabilities depends_on 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/

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/content.md
• docs/frontmatter.md
• docs/mcp_layout.md
• docs/uris.md

Canonical Skill Shape

Create one skill directory under docs/skills/:

docs/
  skills/
    <skill-id>/
      SKILL.md
      references/
        ... (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.

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. depends_on
3. 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
  depends_on: []
  # 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.

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.

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