From a0ae38d0ccee2e44efc723fc4f1faafcbd39e166 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Mon, 22 Jun 2026 09:39:57 -0500 Subject: [PATCH] authoring prompt --- .../instructions/new-skill.instructions.md | 16 -- .github/prompts/skill-bootstrap.prompt.md | 12 -- docs/authoring.md | 53 +++++ docs/prompts/authoring/PROMPT.md | 88 +++++++++ docs/skills/new-skill/SKILL.md | 186 ------------------ zensical.toml | 5 +- 6 files changed, 143 insertions(+), 217 deletions(-) delete mode 100644 .github/instructions/new-skill.instructions.md delete mode 100644 .github/prompts/skill-bootstrap.prompt.md create mode 100644 docs/prompts/authoring/PROMPT.md delete mode 100644 docs/skills/new-skill/SKILL.md diff --git a/.github/instructions/new-skill.instructions.md b/.github/instructions/new-skill.instructions.md deleted file mode 100644 index 878641c..0000000 --- a/.github/instructions/new-skill.instructions.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: New Skill Configuration -description: Route docs/skills edits to the Personal MCP new-skill resource. -applyTo: 'docs/skills/**/*.md' ---- - -When editing files under `docs/skills/`, use `resource://skills/new-skill/document` as the primary guidance source for skill structure and authoring decisions. - -Execution pattern: - -1. Load `resource://skills/new-skill/document` first. -2. Apply only the portions relevant to the file being edited (`SKILL.md` or `references/*.md`). -3. Keep edits minimal and aligned with repository skill conventions. -4. Include source-document links for any feature-level recommendation. - -If task intent is ambiguous, ask one clarifying question before editing. diff --git a/.github/prompts/skill-bootstrap.prompt.md b/.github/prompts/skill-bootstrap.prompt.md deleted file mode 100644 index 9ea17d3..0000000 --- a/.github/prompts/skill-bootstrap.prompt.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: New Skill Bootstrap -description: Create and fully implement a new docs-first skill in this repository. -argument-hint: skill-id and goal for the new skill -agent: agent ---- - -# New Skill Bootstrap - -Use the canonical bootstrap guidance in [docs/skills/new-skill/SKILL.md](../../docs/skills/new-skill/SKILL.md). - -If the request is to create or implement a new skill, load that skill document and follow it as the source of truth. \ No newline at end of file diff --git a/docs/authoring.md b/docs/authoring.md index 1c888f2..17f7f9b 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -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: diff --git a/docs/prompts/authoring/PROMPT.md b/docs/prompts/authoring/PROMPT.md new file mode 100644 index 0000000..4473693 --- /dev/null +++ b/docs/prompts/authoring/PROMPT.md @@ -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). diff --git a/docs/skills/new-skill/SKILL.md b/docs/skills/new-skill/SKILL.md deleted file mode 100644 index f4b8c86..0000000 --- a/docs/skills/new-skill/SKILL.md +++ /dev/null @@ -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.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: -description: - -x-personal-mcp: - id: - version: 1.0.0 - tags: [] - capabilities: - - resource://skills//document - # Optional: only for nested references or metadata overrides. - references: - : - path: references/.md - mime_type: text/markdown - 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//document` -2. `resource://skills//references/` - -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//. -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.md. -2. Add docs/skills//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//document in capabilities. -6. For each top-level `references/.md`, expect `resource://skills//references/` (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.md` with valid frontmatter and a practical skill body. -2. Create and populate `docs/skills//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 diff --git a/zensical.toml b/zensical.toml index b8f0d24..0e3f2bb 100644 --- a/zensical.toml +++ b/zensical.toml @@ -64,12 +64,11 @@ nav = [ { "Security" = "securing.md" }, ] }, { "Prompts" = [ + { "Authoring" = "prompts/authoring/PROMPT.md" }, { "Fill Pytest Scaffold" = "prompts/fill-pytest-scaffold/PROMPT.md" }, + { "MCP Consumer Repo Shim" = "prompts/mcp-consumer-repo-shim/PROMPT.md" }, ] }, { "Skills" = [ - { "New Skill" = [ - { "Overview" = "skills/new-skill/SKILL.md" }, - ] }, { "Copilot" = [ { "Overview" = "skills/copilot-customization/SKILL.md" }, { "VS Code" = "skills/copilot-customization/references/vscode-customization.md" },