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

authoring prompt

Browse Source
This commit is contained in:
John Lancaster
2026-06-22 09:39:57 -05:00
parent 34d3808bbb
commit a0ae38d0cc
6 changed files with 143 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/authoring.md
+53
View File
@@ -74,6 +74,59 @@ When creating or updating a prompt module:
For exact structure, see [Prompt contract](./contracts/prompt.md).
## Prompt Argument Mechanics
When defining prompt inputs, keep argument metadata aligned with the prompt contract and runtime behavior.
1. Define arguments under `x-personal-mcp.arguments` as a map keyed by argument name.
2. Argument names must match Python identifier format: `^[A-Za-z_][A-Za-z0-9_]*$`.
3. Each argument entry supports only:
- `title` (optional)
- `description` (optional)
- `required` (optional, defaults to `false`)
4. Unknown argument fields are rejected by strict frontmatter validation.
5. Prompt argument metadata appears in `resource://catalog/prompts/{prompt_id}`, and MCP prompt objects expose the same arguments for prompt-list/get-prompt workflows.
6. Enum-like constraints are not a native argument field; encode allowed values in `description`.
### Frontmatter Safety Rules
Use these rules to avoid YAML parse failures in prompt and skill frontmatter:
1. Quote any scalar value that contains `:` (for example, `description: "Enum: skill | prompt | shim"`).
2. Prefer quoted scalars for values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
3. If a description needs multiple lines, use a block scalar (`|`) instead of packing punctuation-heavy text into one line.
4. Keep frontmatter keys simple and contract-bound; do not add undeclared argument fields.
### Validation Timing
Run validation immediately after frontmatter edits, not only at the end of a task:
1. First pass after metadata changes: `uv run zensical build`
2. Prompt/skill load verification: `uv run pytest -q`
3. Final full pass before completion: run the full checklist in [Validation Checklist](#validation-checklist)
Example:
```yaml
x-personal-mcp:
arguments:
artifact_type:
title: Artifact type
description: Allowed values are skill, prompt, or shim.
required: true
scope_glob:
title: Scope glob
description: Optional applyTo glob for shim outputs.
required: false
```
References:
1. [Frontmatter contract](./contracts/frontmatter.md)
2. [URI contract](./contracts/uris.md)
3. [Resource-First Pattern Module Architecture](./architecture.md)
4. [Prompt objects concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts)
## Writing Quality Rules
Apply these defaults to all docs pages:
docs/prompts/authoring/PROMPT.md
+88
View File
@@ -0,0 +1,88 @@
---
name: authoring
description: Provide a practical checklist and baseline template for authoring docs-first MCP modules and repository-specific Copilot instruction shims.
x-personal-mcp:
id: authoring
version: 1.0.0
tags:
- authoring
- mcp
- fastmcp
- copilot
- prompts
- scaffolding
capabilities:
- resource://prompts/authoring/document
arguments:
artifact_type:
title: Artifact type
description: "Enum (case-sensitive): skill | prompt | shim."
required: true
artifact_id:
title: Artifact id
description: Lowercase kebab-case id for the module or shim.
required: true
goal:
title: Goal
description: One-sentence capability statement describing what to create and when to use it.
required: true
scope_glob:
title: Scope glob
description: Optional applyTo glob for shim outputs.
required: false
---
# Authoring Bootstrap
Use this prompt to author or update docs-first MCP modules in this repository, including repository-specific Copilot thin shims.
## Inputs
1. artifact_type: one of skill, prompt, shim
2. artifact_id: lowercase kebab-case id
3. goal: one-sentence capability statement
4. optional scope_glob for shim outputs
## Required References
Load only what matches the requested artifact:
1. Authoring workflow and validation policy: [Authoring Guide](../../authoring.md)
2. Prompt metadata and structure: [Prompt Contract](../../contracts/prompt.md)
3. Skill metadata and structure (only for skill outputs): [Skill Contract](../../contracts/skill_contract.md)
4. Thin shim mechanics and path binding: [Skill Usage Mechanics](../../usage.md)
5. Copilot resource attachment and fallback behavior: [Copilot MCP Mechanics](../../copilot.md)
## Workflow
1. Validate required inputs and ask one clarifying question if any required input is missing.
2. Keep ids and slugs aligned with folder names and frontmatter ids.
3. Enforce artifact_type enum values exactly: skill, prompt, shim.
4. If artifact_type is outside the enum, ask one correction question and stop before generating output.
5. Apply YAML safety rules for frontmatter values:
- quote values containing `:`
- prefer quotes for punctuation-heavy scalars
- use block scalars for multiline descriptions
6. Run immediate validation after frontmatter edits:
- `uv run zensical build`
- `uv run pytest -q`
7. Produce only the requested artifact type.
8. Keep guidance deterministic and minimal, with explicit references to source docs.
9. If artifact_type is shim:
- bind one applyTo scope to one primary skill resource URI
- prefer MCP resource attachment first
- if resource attachment is unavailable, use fallback tool order:
1. list_resources
2. read_resource
3. search_patterns
4. get_pattern_by_id
5. get_skill_document_by_id
10. Return created or updated file paths and any validation commands that should be run.
## Output Contract
Return:
1. Files created or updated.
2. Which references were used.
3. Validation commands and outcomes (or commands to run if execution is not requested).
docs/skills/new-skill/SKILL.md
-186
View File
@@ -1,186 +0,0 @@
---
name: new-skill
description: Provide a practical checklist and baseline template for creating a new docs-first MCP skill in this repository.
x-personal-mcp:
id: new-skill
version: 1.0.0
tags:
- fastmcp
- bootstrap
- scaffolding
- skills
- mcp
capabilities:
- resource://skills/new-skill/document
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/`
## 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.
2. Read and follow these docs before implementing a new skill:
- [docs/architecture.md](../../architecture.md)
- [docs/contracts/frontmatter.md](../../contracts/frontmatter.md)
- [docs/mcp_layout.md](../../mcp_layout.md)
- [docs/contracts/uris.md](../../contracts/uris.md)
## Canonical Skill Shape
Create one skill directory under `docs/skills/`:
```text
docs/
skills/
<skill-id>/
SKILL.md
references/
index.md (recommended reference router)
... (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.
5. Include a progressive discovery section in `SKILL.md` that makes selective reference loading explicit.
### 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. `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
# 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.
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
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.
6. Ensure the skill body is structured for progressive discovery and selective reference loading.
## 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