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

agent skills details in docs

Browse Source
This commit is contained in:
John Lancaster
2026-08-30 14:40:32 -05:00
parent 9eb4ccbc6e
commit be579c347e
1 changed files with 14 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/personal_mcp/docs/authoring.md
+14 -2
View File
@@ -26,7 +26,7 @@ Add general documentation as Markdown under `src/personal_mcp/docs/`. Use relati
## Skill Authoring
A skill is a directory containing `SKILL.md`:
Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory containing a required `SKILL.md` file with YAML frontmatter and Markdown instructions:
```yaml
---
@@ -35,7 +35,19 @@ description: <what this skill covers and when to use it>
---
```
Use lowercase kebab-case, and keep the directory name and frontmatter `name` identical. Put optional references beneath the same directory and link to them from `SKILL.md` when readers need to know they exist.
The specification requires:
1. `name` must match the directory name, contain 1-64 lowercase letters, numbers, or hyphens, and have no leading, trailing, or consecutive hyphens.
2. `description` must contain 1-1024 characters and explain both what the skill does and when an agent should use it.
3. The body of `SKILL.md` must contain the instructions an agent needs after selecting the skill.
This repository adds two narrower conventions: names start with a letter, and frontmatter contains only the required `name` and `description`. The specification also defines optional `license`, `compatibility`, `metadata`, and experimental `allowed-tools` fields, but they are not part of this repository's current [Skill Contract](./contracts/skill_contract.md).
Write skills for progressive disclosure. Keep discovery information in the frontmatter, the main workflow in `SKILL.md`, and detailed material in focused files under `references/`. Link to supporting files with paths relative to the skill root, and avoid chains of references that require an agent to open several files before finding the useful content.
The Agent Skills specification also permits `scripts/`, `assets/`, and other supporting directories. This project is primarily a guidance library, so prefer `references/` unless the skill genuinely needs executable or static resources.
[FastMCP's Skills Provider](https://gofastmcp.com/servers/providers/skills) publishes each compliant directory as MCP resources, including the main file, a generated manifest, and any supporting files. The specification's [`skills-ref` validator](https://github.com/agentskills/agentskills/tree/main/skills-ref) can validate an individual skill before the repository-wide checks run.
## Prompt Authoring