Skip to content

Authoring Guide

All authored content lives under src/jsl_mcp/docs/. The same files feed the MCP server and the documentation website.

Source Tree Ownership

src/jsl_mcp/docs/
    *.md                         # General documentation
    prompts/<prompt-id>/
        PROMPT.md                # One MCP prompt
    skills/<skill-name>/
        SKILL.md                 # Main skill guidance
        references/              # Optional supporting material

Do not edit src/jsl_mcp/site/ by hand. It is generated by Zensical.

Documentation Pages

Add general documentation as Markdown under src/jsl_mcp/docs/. Use relative links between pages. Top-level pages need an icon in their frontmatter, and navigation changes belong in zensical.toml.

Skill Authoring

Skills follow the Agent Skills specification. Each skill is a directory containing a required SKILL.md file with YAML frontmatter and Markdown instructions:

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

The specification requires:

  1. name must match the directory name, contain 1-64 lowercase letters, numbers, or hyphens, and have no leading, trailing, or consecutive hyphens.
  2. description must contain 1-1024 characters and explain both what the skill does and when an agent should use it.
  3. The body of SKILL.md must contain the instructions an agent needs after selecting the skill.

This repository adds two narrower conventions: names start with a letter, and frontmatter contains only the required name and description. The specification also defines optional license, compatibility, metadata, and experimental allowed-tools fields, but they are not part of this repository's current Skill Contract.

Write skills for progressive disclosure. Keep discovery information in the frontmatter, the main workflow in SKILL.md, and detailed material in focused files under references/. Link to supporting files with paths relative to the skill root, and avoid chains of references that require an agent to open several files before finding the useful content.

The Agent Skills specification also permits scripts/, assets/, and other supporting directories. This project is primarily a guidance library, so prefer references/ unless the skill genuinely needs executable or static resources.

FastMCP's Skills Provider publishes each compliant directory as MCP resources, including the main file, a generated manifest, and any supporting files. The specification's skills-ref validator can validate an individual skill before the repository-wide checks run.

Prompt Authoring

A prompt is one PROMPT.md file under src/jsl_mcp/docs/prompts/<prompt-id>/. Its prompt frontmatter describes the workflow and arguments; its Markdown body contains the instructions.

Use each declared argument as a {{placeholder}} in the body. The server validates prompt metadata and placeholders when the prompt is discovered.

The Prompt Contract and Frontmatter Contract contain the exact schema.

Validate Changes

uv run zensical build
uv run ruff check .
uv run ty check
uv run pytest

Restart a running server after changing content so every surface reads the latest package data.

For detailed rules, see the content contracts. For writing and site features, use the Zensical documentation skill.