76 lines
2.2 KiB
Markdown
76 lines
2.2 KiB
Markdown
---
|
|
icon: lucide/brain-circuit
|
|
---
|
|
|
|
# Skill Contract
|
|
|
|
This page defines the canonical contract for skills in the docs-first MCP architecture.
|
|
|
|
## Canonical Skill Shape
|
|
|
|
Each skill is one directory under `docs/skills/`:
|
|
|
|
```mermaid
|
|
---
|
|
config:
|
|
treeView:
|
|
rowIndent: 20
|
|
lineThickness: 2
|
|
themeVariables:
|
|
treeView:
|
|
labelColor: '#FFFFFF'
|
|
lineColor: '#FFFFFF'
|
|
---
|
|
treeView-beta
|
|
"docs/"
|
|
"... (other docs)"
|
|
"skills/"
|
|
"<skill-id>/"
|
|
"SKILL.md"
|
|
"references/"
|
|
"... (one or more markdown files, optional nested folders)"
|
|
```
|
|
|
|
Rules:
|
|
|
|
1. `SKILL.md` is required for every skill.
|
|
2. `references/` is the only place for skill-specific supporting docs.
|
|
3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
|
|
4. Skill directories are independent ownership boundaries; no cross-skill file writes.
|
|
|
|
## Metadata Location Constraint
|
|
|
|
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
|
|
2. No `metadata.yaml` sidecar exists in the end state.
|
|
3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
|
|
|
|
## Skill Id Contract
|
|
|
|
`skill-id` is the public identifier and should satisfy all rules below:
|
|
|
|
1. Format: lowercase kebab-case only.
|
|
2. Character set: `a-z`, `0-9`, and `-`.
|
|
3. Must start with a letter.
|
|
4. No underscores, spaces, dots, or uppercase characters.
|
|
5. Directory name should equal `skill-id` in each committed revision.
|
|
6. Frontmatter `id` should equal directory name in each committed revision.
|
|
7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
|
|
|
|
Valid examples:
|
|
|
|
1. `fastapi-uv-docker`
|
|
2. `zensical-docs`
|
|
3. `pytesting`
|
|
|
|
Invalid examples:
|
|
|
|
1. `fastapi_uv_docker`
|
|
2. `Zensical-Docs`
|
|
3. `docs.zensical`
|
|
|
|
## Direct Documentation Inclusion
|
|
|
|
1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
|
|
2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
|
|
|