From be579c347e4d588ae8658ec324531bfa1e62aa2e Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sun, 30 Aug 2026 14:40:32 -0500 Subject: [PATCH] agent skills details in docs --- src/personal_mcp/docs/authoring.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/personal_mcp/docs/authoring.md b/src/personal_mcp/docs/authoring.md index 1d1fbae..ddab076 100644 --- a/src/personal_mcp/docs/authoring.md +++ b/src/personal_mcp/docs/authoring.md @@ -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: --- ``` -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