---
icon: lucide/messages-square
---

# Prompt Contract

This page defines the canonical contract for declarative prompts published through a custom [FastMCP provider](https://gofastmcp.com/servers/providers/custom).

## Canonical Prompt Shape

Each prompt is one self-describing Markdown document:

```mermaid
---
config:
    treeView:
        rowIndent: 20
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
    "docs/prompts/"
      "<prompt-id>/"
        "PROMPT.md"
    "src/personal_mcp/prompts/"
      "content.py"
      "models.py"
      "provider.py"
```

Rules:

1. The parent directory name defines the public prompt id.
2. The nested `prompt` frontmatter block defines version, description, tags, and arguments.
3. Argument declarations define names, descriptions, requiredness, and optional string choices.
4. The Markdown body owns the rendered prompt prose and uses `{{argument_name}}` placeholders.
5. Declared arguments and body placeholders must match exactly.
6. No Python file is added when authoring a prompt.

## Ownership Boundary

1. Each `PROMPT.md` owns both its runtime metadata and prose.
2. Python owns only generic parsing, validation, rendering, and provider behavior.
3. There is no central prompt catalog, generated signature, or metadata sidecar.
4. The provider scans direct children of packaged `docs/prompts/` on each list or get request.
5. Additions, edits, and deletions become visible on the next request without restarting the server.
6. Reload is pull-based; the provider does not watch files or emit proactive change notifications.

## Prompt Id Contract

`prompt-id` is the public identifier and should satisfy all rules below:

1. Format: lowercase kebab-case only.
2. Character set: `a-z`, `0-9`, and `-`.
3. Must start with a letter.
4. No underscores, spaces, dots, or uppercase characters.
5. Directory name should equal `prompt-id` in each committed revision.
6. The provider derives the prompt name from the directory; frontmatter must not duplicate it.
7. Treat `prompt-id` as immutable after release; a rename is a breaking replacement.

Valid examples:

1. `pytest-fill-scaffold`
2. `review-pr-comments`
3. `scaffold-fastapi-service`

Invalid examples:

1. `fill_pytest_scaffold`
2. `Prompt-Template`
3. `docs.prompt`

## Rendering Contract

1. The loader requires one leading YAML frontmatter block and validates its nested `prompt` mapping strictly.
2. All MCP arguments are strings; `choices` optionally restricts accepted values.
3. Missing required arguments, unknown arguments, and invalid choices fail before rendering.
4. An omitted optional value renders as `Not provided`.
5. Unknown prompt ids, malformed metadata, and mismatched placeholders fail immediately.
6. Prompt content is read through [importlib resources](https://docs.python.org/3/library/importlib.resources.html) and does not depend on the working directory.