prompts/docs/contracts/prompt.md

icon

icon
lucide/messages-square

Prompt Contract

This page defines the canonical contract for declarative prompts published through a custom FastMCP provider.

Canonical Prompt Shape

Each prompt is one self-describing Markdown document:

---
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 and does not depend on the working directory.