|
1 | 1 | # Skill Format |
2 | 2 |
|
3 | | -Skills follow the [Agent Skills](https://agentskills.io) open standard. Each skill is a single `SKILL.md` file with YAML frontmatter and a markdown body. |
| 3 | +Skills follow the [Agent Skills](https://agentskills.io) open standard. Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and a markdown body, plus any optional companion files. |
4 | 4 |
|
5 | 5 | ## Structure |
6 | 6 |
|
7 | 7 | ```markdown |
8 | 8 | --- |
9 | 9 | name: code-review |
10 | | -description: Review PRs for style and correctness |
| 10 | +description: | |
| 11 | + Use when reviewing pull requests for style and correctness. |
11 | 12 | tags: |
12 | 13 | - review |
13 | 14 | - quality |
14 | | -version: 1.0.0 |
15 | | -author: |
16 | | - name: Jane Doe |
17 | | - type: human |
18 | 15 | allowed-tools: |
19 | 16 | - Read |
20 | 17 | - Grep |
21 | 18 | - Glob |
| 19 | +metadata: |
| 20 | + author: |
| 21 | + name: Jane Doe |
| 22 | + type: human # human | agent |
| 23 | + platform: claude-code # only when type=agent |
| 24 | + version: "1.0.0" |
| 25 | + modified-by: # append-only provenance |
| 26 | + - name: codex-cli |
| 27 | + type: agent |
| 28 | + platform: codex-cli |
| 29 | + date: "2026-04-12T10:30:00Z" |
22 | 30 | --- |
23 | 31 |
|
24 | | -## Instructions |
| 32 | +## Overview |
25 | 33 |
|
26 | | -Review pull requests for: |
27 | | -- Code style consistency |
28 | | -- Correctness of logic |
29 | | -- Test coverage |
| 34 | +1-2 sentence core principle of the skill. |
| 35 | + |
| 36 | +## When to Use |
| 37 | + |
| 38 | +- Triggering conditions and symptoms |
| 39 | + |
| 40 | +## Core Pattern |
| 41 | + |
| 42 | +The main technique or pattern (before/after for techniques). |
30 | 43 | ``` |
31 | 44 |
|
32 | 45 | ## Frontmatter Fields |
33 | 46 |
|
34 | 47 | | Field | Required | Description | |
35 | 48 | |-------|----------|-------------| |
36 | | -| `name` | Yes | Skill name matching `[a-z0-9]+(-[a-z0-9]+)*`, 1-64 chars | |
37 | | -| `description` | Yes | What the skill does, max 1024 chars | |
38 | | -| `version` | No | Semantic version (e.g., `1.0.0`) | |
39 | | -| `author.name` | No | Author name | |
40 | | -| `author.type` | No | `human` or `agent` | |
41 | | -| `author.platform` | No | Platform name (e.g., `claude-code`) | |
| 49 | +| `name` | Yes | Skill name matching `[a-z0-9]+(-[a-z0-9]+)*`, 1-64 chars. Must equal the directory name. | |
| 50 | +| `description` | Yes | What the skill does — start with "Use when…". Max 1024 chars. | |
42 | 51 | | `tags` | No | List of classification tags | |
43 | | -| `allowed-tools` | No | List of tools the skill may use | |
44 | | -| `modified-by` | No | Modification history entries | |
| 52 | +| `allowed-tools` | No | Tools the skill may use. No empty entries. | |
| 53 | +| `metadata.author.name` | No | Author name | |
| 54 | +| `metadata.author.type` | No | `human` or `agent` | |
| 55 | +| `metadata.author.platform` | No | Platform name (e.g. `claude-code`) — used when `type: agent` | |
| 56 | +| `metadata.version` | No | Semantic version (e.g. `1.0.0`); defaults to `0.0.1` on `skill create` | |
| 57 | +| `metadata.modified-by` | No | Append-only modification history (set via `skern skill edit --modified-by`) | |
| 58 | + |
| 59 | +`name` and `description` are the only hard requirements. The rest help discovery, validation, and provenance. |
45 | 60 |
|
46 | 61 | ## Body |
47 | 62 |
|
48 | 63 | The markdown body contains the skill's instructions. This is what the agent reads when the skill is activated. It must be non-empty. |
49 | 64 |
|
| 65 | +The recommended body structure (also what `skern skill create` scaffolds) is: |
| 66 | + |
| 67 | +1. **Overview** — 1-2 sentence core principle |
| 68 | +2. **When to Use** — triggering conditions |
| 69 | +3. **Core Pattern** — the main technique |
| 70 | +4. **Quick Reference** — scannable summary |
| 71 | +5. **Common Mistakes** — frequent errors and fixes |
| 72 | + |
| 73 | +See [Writing Skills](/writing-skills) for details on what makes a discoverable, well-structured skill. |
| 74 | + |
50 | 75 | ## Author Provenance |
51 | 76 |
|
52 | | -Skills track author metadata and an optional `modified-by` history. `skern skill show` displays the full provenance chain when present, including editor name, type (human/agent), platform, and date. |
| 77 | +Skills track an author and an append-only `modified-by` history. `skern skill show` prints the full provenance chain when present, including editor name, type (human/agent), platform, and date. `skern skill edit --modified-by <name>` adds a new entry without overwriting earlier ones. |
53 | 78 |
|
54 | 79 | ## Folder Structure |
55 | 80 |
|
56 | | -Skills can include additional files alongside `SKILL.md` — helper scripts, templates, configuration files, and other assets. When a skill is installed to a platform, the entire directory is copied. |
| 81 | +A skill is a directory. `SKILL.md` is the manifest; sibling files travel with it. |
57 | 82 |
|
58 | 83 | ``` |
59 | 84 | my-skill/ |
60 | 85 | ├── SKILL.md |
| 86 | +├── references/ |
| 87 | +│ └── notes.md |
61 | 88 | ├── scripts/ |
62 | 89 | │ ├── convert.py |
63 | 90 | │ └── setup.sh |
64 | 91 | └── assets/ |
65 | 92 | └── template.json |
66 | 93 | ``` |
67 | 94 |
|
68 | | -The `scripts/` directory is language-agnostic — skills can include Python, shell, JavaScript, or any other scripts. The agent decides which language is appropriate for the skill. |
| 95 | +When a skill is installed to a platform, the **entire directory** is copied. The `scripts/` directory is language-agnostic — skills can include Python, shell, JavaScript, or any other scripts. The agent decides which language is appropriate. |
69 | 96 |
|
70 | | -Use `skern skill show <name>` to see which files are bundled with a skill, and `skern skill validate <name>` to check that files referenced in the skill body actually exist. |
| 97 | +`skern skill validate <name>` checks that files referenced in the body (via backticks or markdown links) actually exist in the skill directory. Missing references produce **warnings**, not errors. `skern skill show <name>` lists every file bundled with the skill. |
71 | 98 |
|
72 | 99 | ## Creating Skills |
73 | 100 |
|
74 | 101 | Use `skern skill create` to scaffold a new skill: |
75 | 102 |
|
76 | 103 | ```sh |
77 | 104 | skern skill create code-review \ |
78 | | - --description "Review PRs for style and correctness" \ |
| 105 | + --description "Use when reviewing PRs for style and correctness" \ |
79 | 106 | --author "Jane Doe" \ |
80 | | - --author-type human |
| 107 | + --author-type human \ |
| 108 | + --version 1.0.0 \ |
| 109 | + --tags review,quality |
81 | 110 | ``` |
82 | 111 |
|
83 | | -Or seed from another skill. `--from-template <dir>` requires a **skill directory** |
84 | | -— a directory containing `SKILL.md` and any optional companion files |
85 | | -(`references/`, `templates/`, `VENDORED.md`, …). Skern parses the template's |
86 | | -frontmatter and copies every sibling into the new skill: |
| 112 | +Or seed from another skill. `--from-template <dir>` requires a **skill directory** — a directory containing `SKILL.md` and any optional companion files (`references/`, `templates/`, `VENDORED.md`, …). Skern parses the template's frontmatter and copies every sibling into the new skill: |
| 113 | + |
| 114 | +```sh |
| 115 | +skern skill create code-review \ |
| 116 | + --from-template ~/.skern/skills/source-template |
| 117 | +``` |
| 118 | + |
| 119 | +A bare file path (a `SKILL.md` or a body-only markdown file) is rejected with an error pointing at the parent directory. The CLI `<name>` argument always wins over the template's name; other flags (`--description`, `--tags`, `--author*`, `--version`) override template values when explicitly set, otherwise the template's values are preserved. |
| 120 | + |
| 121 | +## Importing Skills |
| 122 | + |
| 123 | +`skern skill import <url>` pulls an existing skill into the registry from a GitHub repository directory or gist: |
87 | 124 |
|
88 | 125 | ```sh |
89 | | -# Seeds the new skill from an existing skill directory. SKILL.md frontmatter |
90 | | -# (description, tags, metadata.author, metadata.version) is preserved; all |
91 | | -# sibling files and subdirectories are copied alongside the new SKILL.md. |
92 | | -skern skill create code-review --from-template ~/.skern/skills/source-template |
| 126 | +skern skill import https://github.com/owner/repo/tree/main/skills/code-review |
| 127 | +skern skill import https://gist.github.com/<id> |
| 128 | +skern skill import <url> --name local-name --scope project |
93 | 129 | ``` |
94 | 130 |
|
95 | | -A bare file path (e.g., a `SKILL.md` or a markdown body file) is rejected with |
96 | | -an error pointing you at the parent directory. The CLI `<name>` argument |
97 | | -always wins over the template's `name`; other flags |
98 | | -(`--description`, `--tags`, `--author*`, `--version`) override template values |
99 | | -when explicitly set, otherwise the template's values are preserved. |
| 131 | +Overlap detection runs on import too — pass `--force` to override a near-duplicate block. |
0 commit comments