@kensio/skill-template 1.12.0 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/README.md +11 -3
  3. package/package.json +8 -3
  4. package/skills/skill-template/SKILL.md +81 -53
package/.claude-plugin/plugin.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
3
  "name": "skill-template",
4
- "version": "1.12.0",
5
- "description": "A copy-and-edit starting point for a new Claude Code skill.",
4
+ "version": "1.13.0",
5
+ "description": "A copy-and-edit starting point for a new agent skill.",
6
6
  "author": {
7
7
  "name": "Kensio Software",
8
8
  "email": "hugh@kensiosoftware.co.uk"
package/README.md CHANGED
@@ -1,8 +1,16 @@
1
1
  # @kensio/skill-template
2
2
 
3
- A copy-and-edit starting point for writing a new Claude Code skill, covering the folder layout,
4
- `SKILL.md` frontmatter, how to word a description so the skill actually triggers, and how to release
5
- a version bump.
3
+ A copy-and-edit starting point for writing an agent skill, covering the directory layout the
4
+ [Agent Skills specification](https://agentskills.io/specification) defines, how to word a
5
+ description so the skill actually triggers, and how to publish one from this repository.
6
+
7
+ A skill is a directory holding a `SKILL.md`. Claude Code, Codex, Cursor, Copilot, Gemini CLI and the
8
+ other implementations all read that same directory, and the plugin wrapper in this repository is one
9
+ way of delivering it.
10
+
11
+ ```bash
12
+ npx @kensio/skills add skill-template
13
+ ```
6
14
 
7
15
  ```
8
16
  /plugin marketplace add KensioSoftware/kensio.ai
package/package.json CHANGED
@@ -1,13 +1,18 @@
1
1
  {
2
2
  "name": "@kensio/skill-template",
3
- "version": "1.12.0",
4
- "description": "A copy-and-edit starting point for a new Claude Code skill.",
3
+ "version": "1.13.0",
4
+ "description": "A copy-and-edit starting point for a new agent skill.",
5
5
  "keywords": [
6
+ "agent-skills",
6
7
  "claude",
7
8
  "claude-code",
8
9
  "claude-code-plugin",
10
+ "codex",
11
+ "copilot",
12
+ "cursor",
9
13
  "kensio",
10
- "skill"
14
+ "skill",
15
+ "skill-md"
11
16
  ],
12
17
  "homepage": "https://kensio.ai",
13
18
  "license": "Apache-2.0",
package/skills/skill-template/SKILL.md CHANGED
@@ -1,80 +1,108 @@
1
1
  ---
2
2
  name: skill-template
3
- description: Scaffold a new Claude Code skill in this repo, creating the plugin folder, package.json, plugin.json and SKILL.md, and registering it in the marketplace. Use when the user asks to "add a new skill", "create a skill", or "start a new plugin" in the kensio.ai repo.
3
+ description: Scaffold a new agent skill, writing the SKILL.md and its frontmatter to the Agent Skills specification, then wrapping it as a plugin in this repo with package.json, plugin.json and a marketplace entry. Use when the user asks to "add a new skill", "create a skill", "write a SKILL.md" or "start a new plugin", and when checking whether an existing skill is portable between agents.
4
+ license: Apache-2.0
5
+ metadata:
6
+ version: "1.13.0"
4
7
  ---
5
8
 
6
- # Skill Template
9
+ # Skill template
7
10
 
8
- A starting point for adding a new skill to this repo. Copy the structure below, replace the
9
- placeholders, then run the validation scripts.
11
+ A skill is a directory with a `SKILL.md` in it. That directory is the artefact, and every agent
12
+ reads it. The plugin folder around it in this repository is packaging for one of them.
10
13
 
11
- ## Layout
14
+ Write the skill first, following the [specification](https://agentskills.io/specification). Then
15
+ wrap it.
12
16
 
13
- Every skill lives in its own self-contained plugin folder:
17
+ ## The skill directory
14
18
 
15
19
  ```
16
- plugins/<skill-name>/
17
- ├── package.json # npm package: @kensio/<skill-name>
18
- ├── .claude-plugin/
19
- │ └── plugin.json # name, version, description, author
20
- └── skills/
21
- └── <skill-name>/
22
- ├── SKILL.md
23
- ├── reference/ # optional, loaded only when linked to
24
- └── scripts/ # optional, anything the skill runs
20
+ <skill-name>/
21
+ ├── SKILL.md
22
+ ├── references/ # optional, loaded only when linked to
23
+ ├── scripts/ # optional, anything the skill runs
24
+ └── assets/ # optional, templates and data files
25
25
  ```
26
26
 
27
- Anything under `skills/` ships, because that is what `package.json` lists in `files`. A script the
28
- skill runs belongs there too, and never at the plugin root.
27
+ Those three subdirectory names come from the specification. An agent that supports skills at all
28
+ knows this shape, whether it reads the directory from `.agents/skills/`, `.claude/skills/`,
29
+ `.github/skills/` or a plugin.
29
30
 
30
- **A plugin folder must be self-contained.** Never reference files outside it with `../`, because
31
- plugins are copied, zipped, and installed standalone, so those paths will not resolve.
31
+ **Every path a skill mentions is relative to its own directory.** The directory gets copied out on
32
+ its own, unzipped somewhere unrelated, and installed under a name this repository never sees. A
33
+ command written as `node skills/<skill-name>/scripts/check.mjs` works here and nowhere else. Write
34
+ `node scripts/check.mjs`. `pnpm validate:skills` fails the build on any path that reaches outside
35
+ the skill, which is the check that caught this after it had already shipped once.
32
36
 
33
- ## Steps
37
+ ## Frontmatter
34
38
 
35
- 1. Create `plugins/<skill-name>/` following the layout above.
36
- 2. Copy `package.json` from an existing plugin, then set `name` to `@kensio/<skill-name>` and the
39
+ ```markdown
40
+ ---
41
+ name: <skill-name>
42
+ description: <what it does, then when to use it. Include the words and phrases a user would actually type>
43
+ license: Apache-2.0
44
+ metadata:
45
+ version: "0.0.0"
46
+ ---
47
+ ```
48
+
49
+ - `name` is lowercase, hyphenated, at most 64 characters, and matches the containing directory.
50
+ - `description` is the _only_ thing an agent sees when deciding whether to load the skill. It
51
+ carries the whole triggering burden. State what the skill does, then when to use it, in third
52
+ person. Concrete trigger phrases beat abstract summaries. 1024 characters is the ceiling.
53
+ - `license` and `metadata` travel with the directory. A copy in someone's `.agents/skills/` has no
54
+ package.json beside it, and these are then the only record of what it is and where it came from.
55
+ The release sets `metadata.version`. Never edit that number by hand.
56
+ - The specification allows two more keys. `compatibility` states an environment requirement, such as
57
+ a binary the scripts need. `allowed-tools` restricts the tools the skill may use, and support for
58
+ it varies between agents. Any other key fails validation.
59
+
60
+ Keep `SKILL.md` under 500 lines. It is instructions for an agent, and documentation for a human
61
+ belongs in the README. Push detail into `references/` and link to it. The body stays cheap to load
62
+ and the details are read only when needed.
63
+
64
+ ## Wrapping it as a plugin
65
+
66
+ Claude Code installs skills as plugins, so each one here has a plugin folder around it:
67
+
68
+ ```
69
+ plugins/<skill-name>/
70
+ ├── package.json # npm package: @kensio/<skill-name>
71
+ ├── README.md # for humans arriving from npm or GitHub
72
+ ├── .claude-plugin/
73
+ │ └── plugin.json # name, version, description, author
74
+ └── skills/
75
+ └── <skill-name>/ # the skill directory above
76
+ ```
77
+
78
+ 1. Create `plugins/<skill-name>/` following that layout.
79
+ 2. Copy `package.json` from an existing plugin, then set `name` to `@kensio/<skill-name>` and
37
80
  `repository.directory` to `plugins/<skill-name>`.
38
81
  3. Copy `.claude-plugin/plugin.json`, then set `name` and `description`.
39
- 4. Set the `version` in both files to whatever the other plugins currently carry. Versions move in
40
- lockstep across the whole repo, and the release workflow is what changes them. Never pick a new
41
- number by hand.
42
- 5. Write `skills/<skill-name>/SKILL.md` (see frontmatter below).
82
+ 4. Set the `version` in both files, and in the `SKILL.md` frontmatter, to whatever the other plugins
83
+ currently carry. Versions move in lockstep across the whole repo and the release workflow is what
84
+ changes them. Never pick a new number by hand.
85
+ 5. Write `skills/<skill-name>/SKILL.md`.
43
86
  6. Add an entry to `.claude-plugin/marketplace.json` with a matching `name`, a `source` of
44
87
  `"./plugins/<skill-name>"`, and a description.
45
- 7. Run `pnpm check`. This validates the manifests, asserts the lockstep version, and runs the prose
46
- gate described below.
88
+ 7. Run `pnpm check`.
47
89
 
48
- `scripts/set-version.mjs` and `scripts/publish-npm.mjs` both read the `plugins/` directory, so a new
49
- folder is versioned and included in the next release without being listed anywhere.
90
+ Anything under `skills/` ships, because that is what `package.json` lists in `files`. A script the
91
+ skill runs belongs there too, and never at the plugin root.
92
+
93
+ **A plugin folder must be self-contained.** Never reference files outside it with `../`. Plugins are
94
+ copied, zipped and installed standalone, and those paths will not resolve.
95
+
96
+ Nothing else needs telling about the new folder. `scripts/set-version.mjs`,
97
+ `scripts/publish-npm.mjs` and `scripts/build-zips.mjs` all read the `plugins/` directory, so a new
98
+ skill is versioned, bundled into `@kensio/skills`, zipped onto the release and published without
99
+ being listed anywhere else.
50
100
 
51
101
  **A brand new package still needs one manual first publish.** npm trusted publishing cannot create a
52
102
  package that does not exist, because the trusted publisher is configured against a package already
53
103
  on the registry. The release reports the commands and carries on. See "npm publishing" in the
54
104
  repository README.
55
105
 
56
- ## SKILL.md frontmatter
57
-
58
- ```markdown
59
- ---
60
- name: <skill-name>
61
- description: <what it does, then when to use it. Include the words and phrases a user would actually type>
62
- ---
63
- ```
64
-
65
- - `name` must be kebab-case and match the containing directory.
66
- - `description` is the _only_ thing Claude sees when deciding whether to load the skill. It carries
67
- the whole triggering burden. State what the skill does, then when to use it, in third person.
68
- Concrete trigger phrases beat abstract summaries.
69
- - Optional frontmatter worth knowing: `allowed-tools` (restrict the tools the skill may use) and
70
- `disable-model-invocation: true` (user-invocable only, via `/<skill-name>`).
71
-
72
- ## Writing the body
73
-
74
- Keep `SKILL.md` short and imperative. It is instructions for Claude. Documentation for a human
75
- belongs in the README. Push detail into sibling files (`reference/`, `examples/`) and link to them.
76
- The body stays cheap to load and the details are read only when needed.
77
-
78
106
  ## Prose
79
107
 
80
108
  `pnpm check` runs `pnpm prose`, which fails the build on em dashes, semicolons, and five sentence
@@ -91,7 +119,7 @@ node plugins/technical-prose-style/skills/technical-prose-style/scripts/prose-ch
91
119
  ## Releasing
92
120
 
93
121
  Releasing is automatic. Merging to `main` releases, and the version comes from the pull request
94
- title: `fix:` for a patch, `feat:` for a minor, `feat!:` or a `BREAKING CHANGE` footer for a major.
122
+ title. `fix:` for a patch, `feat:` for a minor, `feat!:` or a `BREAKING CHANGE` footer for a major.
95
123
  A `docs:` or `chore:` title releases nothing.
96
124
 
97
125
  Every plugin is set to the new version together. A released version means the same commit wherever