---
name: new-skill
description: Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.
argument-hint: What skill are you creating, and what problem should it solve?
x-personal-mcp:
  id: new-skill
  version: 1.0.0
  tags:
    - fastmcp
    - bootstrap
    - scaffolding
    - skills
    - mcp
  capabilities:
    - resource://skills/new-skill/document
  depends_on: []
  references: {}
---

# 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](../../architecture.md)
  - [docs/content.md](../../content.md)
  - [docs/frontmatter.md](../../frontmatter.md)
  - [docs/mcp_layout.md](../../mcp_layout.md)
  - [docs/uris.md](../../uris.md)

## Canonical Skill Shape

Create one skill directory under `docs/skills/`:

```text
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:

```yaml
---
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/<skill-id>/.
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-id>/SKILL.md.
2. Add docs/skills/<skill-id>/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/<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.

## 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