authoring prompt
This commit is contained in:
John Lancaster
@@ -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
|
||||
Reference in New Issue
Block a user