john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

started prompt mechanics

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 20:27:32 -05:00
parent 098a2418ee
commit f8e0c14d46
12 changed files with 809 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+19 -1
View File
@@ -16,6 +16,8 @@ The system is complete in three layers:
2. Catalog resources provide normalized discovery.
3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
Prompt documents under `docs/prompts/` are also indexed and exposed as first-class catalog and prompt surfaces.
This architecture is anchored by three contracts:
1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
@@ -55,6 +57,17 @@ Each skill publishes resource families:
The document resource returns canonical Markdown, while clients can perform any downstream section extraction they need.
### Prompt Modules
Prompt guidance can be authored in `docs/prompts/` using either canonical prompt directories (`docs/prompts/<prompt-id>/PROMPT.md`) or legacy markdown files during migration.
Prompt modules publish two additive surfaces:
1. prompt resources for catalog and document retrieval
2. MCP prompt objects for prompt-list/get-prompt style client workflows
This keeps authored markdown as source-of-truth while allowing clients to discover and invoke prompts directly.
### Catalog Module
The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment.
@@ -63,6 +76,8 @@ Typical catalog resources:
1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
3. resource://catalog/prompts_index
4. resource://catalog/prompts/{prompt_id}
Only canonical catalog resources are part of the runtime contract in this phase.
@@ -139,6 +154,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy
3. resource://catalog/skills_index
4. resource://catalog/skills/{skill_id}
5. resource://docs/{path*}
6. resource://catalog/prompts_index
7. resource://catalog/prompts/{prompt_id}
8. resource://prompts/{prompt_id}/document
Validation rules:
@@ -200,7 +218,7 @@ Markdown remains easy to review, while contracts remain stable for clients.
### Client Independence
Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. However, MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
Clients can use Ask, Edit, or Agent modes without requiring prompt-first orchestration. Prompt objects are available as an additive MCP surface, while resource retrieval remains the canonical source path. MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path.
## Authoring and Publishing Lifecycle
docs/frontmatter.md
+31
View File
@@ -6,6 +6,8 @@ icon: lucide/braces
This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.
Prompt modules use the same contract style in `docs/prompts/<prompt-id>/PROMPT.md` with prompt-specific capability and optional typed argument metadata.
## Anthropic Frontmatter Support
Across Anthropic API and Agent Skills surfaces:
@@ -97,6 +99,35 @@ Rules for `x-personal-mcp`:
5. `depends_on` is optional and lists other skill ids.
6. `references` is an optional map keyed by `ref-id` for overrides and nested entries.
Prompt-specific additions:
1. `arguments` is an optional map keyed by argument name.
2. Each argument supports `type`, optional `description`, optional `required`, optional `default`, and optional `enum`.
3. `type` must be one of `string`, `number`, `integer`, `boolean`, `array`, or `object`.
4. Prompt `capabilities` must include `resource://prompts/<prompt-id>/document`.
Example prompt frontmatter:
```yaml
---
name: initial-test-structure
description: Generate a baseline pytest test layout for a target scope.
x-personal-mcp:
id: initial-test-structure
version: 1.0.0
tags:
- pytest
- testing
capabilities:
- resource://prompts/initial-test-structure/document
arguments:
target_scope:
type: string
description: Target package or module under test.
required: true
---
```
Reference entry rules:
1. `ref-id` is lowercase kebab-case.
docs/prompts/testing/inital_test_structure.md
+5
View File
@@ -0,0 +1,5 @@
# Prompt For Creating Initial Test Structure
Create an initial test structure in `./tests` based around pytest best practices.
This is a placeholder until there's more content
docs/skills/new-skill/SKILL.md
+20
View File
@@ -27,6 +27,20 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
2. One-sentence capability statement (what it does and when to use it)
3. Optional list of references to include under `references/`
## Progressive Discovery Requirement
Every new skill created from this template should be optimized for progressive discovery, so agents load only the most relevant references in the right order.
Required sections for new skills:
1. `When to Use` with concrete trigger conditions.
2. `How To Use This Skill` with a short intent-first flow.
3. `Intent Router` mapping common task intents to specific reference files.
4. `Load Order` and `Load Budget` defaults (for example, start with one baseline reference, then one stack-specific reference).
5. `Output Contract` requiring the references consulted and the discovery path used.
If the domain includes naming or hierarchy conventions, include a dedicated naming trigger section that is consulted before structure recommendations.
## Source of Truth and Required References
1. Use this file as the baseline template for new skill authoring.
@@ -47,6 +61,7 @@ docs/
<skill-id>/
SKILL.md
references/
index.md (recommended reference router)
... (optional markdown files, nested folders allowed)
```
@@ -56,6 +71,7 @@ Rules:
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.
5. Include a progressive discovery section in `SKILL.md` that makes selective reference loading explicit.
### Framing
@@ -148,6 +164,9 @@ Compatibility rule:
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.
8. Add `When to Use`, `How To Use This Skill`, `Intent Router`, `Load Order`, and `Load Budget` sections in the skill body.
9. Ensure the `Output Contract` requires reporting consulted references and the decision path.
10. If naming conventions are part of the domain, include a naming trigger section and place naming guidance early in the flow.
## Required Outcomes
@@ -156,6 +175,7 @@ Compatibility rule:
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.
6. Ensure the skill body is structured for progressive discovery and selective reference loading.
## Validation
docs/skills/pytest-scaffolding/SKILL.md
+44 -16
View File
@@ -1,6 +1,6 @@
---
name: pytest-scaffolding
description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Use when you need best-practice guidance and source links for core pytest, FastAPI testing, and SQLAlchemy testing."
description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Optimized for progressive discovery so naming and hierarchy guidance are loaded first when shaping or reorganizing tests."
argument-hint: "Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)"
x-personal-mcp:
id: pytest-scaffolding
@@ -29,24 +29,50 @@ Repository defaults:
- pytest settings live in `pyproject.toml` under `[tool.pytest.ini_options]`.
- strict marker checking is expected (`--strict-markers`).
## Reference Map
## Progressive Discovery Start
Use this map to open only the reference that matches your immediate need.
Use this load order by default so guidance stays targeted and naming conventions are pulled in early:
- Core pytest practices and command patterns: [pytest-docs.md](./references/pytest-docs.md)
- Naming conventions and hierarchy organization: [naming-and-organization.md](./references/naming-and-organization.md)
- FastAPI-specific testing patterns: [fastapi-testing.md](./references/fastapi-testing.md)
- SQLAlchemy-specific testing patterns: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
1. Classify intent first: naming and organization, baseline pytest mechanics, FastAPI testing, SQLAlchemy testing, or mixed.
2. For create/restructure/rename tasks, load [naming-and-organization.md](./references/naming-and-organization.md) first.
3. Load [pytest-docs.md](./references/pytest-docs.md) next for fixture and marker defaults.
4. Load at most one stack-specific reference unless the request is explicitly mixed stack.
5. If confidence is low after two references, ask one clarifying question before loading more.
Load budget defaults:
1. Single-stack task: 1 to 2 references.
2. Mixed-stack task: up to 3 references.
3. Avoid loading all references unless the user explicitly asks for a broad audit.
## Intent Router
Open only the reference that matches the immediate task.
1. Naming, file layout, discovery prefixes, class/function naming: [naming-and-organization.md](./references/naming-and-organization.md)
2. Fixture layering, marker policy, collect-only and fast-path commands: [pytest-docs.md](./references/pytest-docs.md)
3. Route tests, dependency overrides, lifespan handling: [fastapi-testing.md](./references/fastapi-testing.md)
4. Session and transaction fixtures, async ORM behavior: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
## Naming Pull-In Triggers
Always consult [naming-and-organization.md](./references/naming-and-organization.md) before recommending structure when any of these are true:
1. New tests are being added.
2. Existing tests are being reorganized or renamed.
3. The request mentions conventions, readability, hierarchy, or discoverability.
4. The task introduces parametrization where case naming affects failure readability.
## Baseline Best Practices
These are stable defaults regardless of stack:
1. Mirror `src/` into `tests/` so ownership and coverage are obvious.
2. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
3. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
4. Separate fast feedback (`-m unit`) from broader integration/external lanes.
5. Validate structure early with collection checks before expanding assertions.
1. Apply pytest naming and hierarchy conventions first so discovery and ownership stay predictable; see [naming-and-organization.md](./references/naming-and-organization.md).
2. Mirror `src/` into `tests/` so ownership and coverage are obvious.
3. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
4. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
5. Separate fast feedback (`-m unit`) from broader integration/external lanes.
6. Validate structure early with collection checks before expanding assertions.
## Stack-Specific Guidance
@@ -76,7 +102,9 @@ Use these commands to check structure and execution lanes:
## Output Contract
When this skill is applied, return:
1. Which references were consulted.
2. Recommended structure, naming, fixture, and marker decisions.
3. Exact validation commands.
4. Relevant source-doc links for any non-trivial recommendation.
5. Risks, assumptions, or open questions.
2. The discovery path used (intent classification, load order, and why).
3. Recommended structure, naming, fixture, and marker decisions.
4. Concrete naming outcomes: file/module naming pattern, class usage decision, and any parametrization `ids` conventions.
5. Exact validation commands.
6. Relevant source-doc links for any non-trivial recommendation.
7. Risks, assumptions, or open questions.
docs/testing.md
+1
View File
@@ -0,0 +1 @@
# Testing
docs/uris.md
+25
View File
@@ -15,6 +15,9 @@ The public, preferred URIs are:
3. `resource://skills/{skill_id}/document`
4. `resource://skills/{skill_id}/references/{ref_id}`
5. `resource://docs/{path*}`
6. `resource://catalog/prompts_index`
7. `resource://catalog/prompts/{prompt_id}`
8. `resource://prompts/{prompt_id}/document`
Contract intent:
@@ -52,6 +55,23 @@ Contract intent:
2. Supports nested paths via RFC6570 wildcard expansion.
3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
### `resource://catalog/prompts_index`
1. Returns a compact list of prompt records for discovery.
2. Contains one entry per `prompt_id`.
3. Includes `id`, `name`, `description`, `tags`, `version`, and canonical document URI.
### `resource://catalog/prompts/{prompt_id}`
1. Returns one normalized record for `prompt_id`.
2. Includes prompt argument metadata when declared in frontmatter.
3. Returns not found when `prompt_id` does not exist.
### `resource://prompts/{prompt_id}/document`
1. Returns the canonical prompt markdown document.
2. `prompt_id` must satisfy lowercase kebab-case rules.
## Template Parameter And Validation Rules
### `skill_id`
@@ -72,6 +92,11 @@ Contract intent:
4. Resolves only inside `docs/`.
5. Markdown-only in the end state, meaning `.md` files.
### `prompt_id`
1. Lowercase kebab-case.
2. Must be unique across prompt ids and must not collide with skill ids.
## URI Versioning Policy
Default rule:
docs/usage.md
+14
View File
@@ -22,6 +22,8 @@ In Copilot Chat, there are two distinct mechanisms:
In this repository, skill guidance is exposed as MCP resources, not as server-owned prompt execution. Copilot remains the orchestrator.
Prompt guidance is now exposed through both prompt resources and MCP prompt objects. Prompt objects are additive; authored markdown remains the canonical source.
## Background Mechanics
### What the server publishes
@@ -30,12 +32,18 @@ In this repository, skill guidance is exposed as MCP resources, not as server-ow
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://catalog/prompts_index`
4. `resource://catalog/prompts/{prompt_id}`
Each skill publishes a canonical Markdown document resource:
1. `resource://skills/<skill-id>/document`
2. `resource://skills/<skill-id>/references/<ref-id>`
Prompts publish a canonical prompt document resource:
1. `resource://prompts/<prompt-id>/document`
The document payload is loaded from `docs/skills/<skill-id>/SKILL.md` and returned with metadata.
### What Copilot does as the client
@@ -74,6 +82,10 @@ In practice, there are two reliable ways to make skill content available in chat
1. explicit resource attachment through `Add Context > MCP Resources` or `MCP: Browse Resources`
2. MCP tool invocation using `list_resources`/`read_resource` (ResourcesAsTools), with thin catalog tools as parity fallback
For prompt content, there is a third option when the client supports MCP prompt APIs:
1. prompt-object discovery and invocation through MCP prompt lists and `get_prompt`
Instruction quality and metadata quality still matter, because they influence whether Copilot recognizes that the MCP server is relevant and chooses the tool path well.
## Operating Pattern
@@ -209,6 +221,8 @@ Compatibility aliases for clients that use `catalog_*` naming are also available
1. `catalog_search_patterns`
2. `catalog_get_pattern_by_id`
3. `catalog_get_skill_document_by_id`
4. `catalog_search_prompts`
5. `catalog_get_prompt_by_id`
Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.