authoring prompt

2026-06-22 09:39:57 -05:00
parent 34d3808bbb
commit a0ae38d0cc
6 changed files with 143 additions and 217 deletions
@@ -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.
@@ -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.
@@ -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:
@@ -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).
@@ -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
@@ -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" },