@theholocron/skills 1.1.3 → 1.2.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.
- package/README.md +2 -0
- package/package.json +3 -4
- package/skills/holocron-skill-skill/SKILL.md +134 -0
- package/skills/holocron-skill-util/SKILL.md +274 -0
package/README.md
CHANGED
|
@@ -29,6 +29,8 @@ Skills authored and maintained in this repo. Published inside the npm package.
|
|
|
29
29
|
| [`holocron-skill-config`](./skills/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `theholocron/configs` |
|
|
30
30
|
| [`holocron-skill-client`](./skills/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `theholocron/clients` |
|
|
31
31
|
| [`holocron-skill-plugin`](./skills/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
|
|
32
|
+
| [`holocron-skill-util`](./skills/holocron-skill-util/SKILL.md) | Scaffold a new `@theholocron/*-utils` package in `theholocron/utils` |
|
|
33
|
+
| [`holocron-skill-skill`](./skills/holocron-skill-skill/SKILL.md) | Add a new owned skill to `theholocron/skills` |
|
|
32
34
|
|
|
33
35
|
## External skills
|
|
34
36
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/skills",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Shared agent skill registry.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -40,10 +40,9 @@
|
|
|
40
40
|
"@semantic-release/git": "^10.0.1",
|
|
41
41
|
"@semantic-release/github": "^12.0.9",
|
|
42
42
|
"@theholocron/cli": "catalog:holocron",
|
|
43
|
-
"@theholocron/commitlint-config": "
|
|
43
|
+
"@theholocron/commitlint-config": "catalog:configs",
|
|
44
44
|
"@theholocron/holocron-plugin-github": "catalog:holocron",
|
|
45
|
-
"@theholocron/semantic-release-config": "
|
|
46
|
-
"@semantic-release/npm": "^13.0.0",
|
|
45
|
+
"@theholocron/semantic-release-config": "catalog:configs",
|
|
47
46
|
"conventional-changelog-conventionalcommits": "^10.2.1",
|
|
48
47
|
"semantic-release": "^25.0.7",
|
|
49
48
|
"typescript": "^5.9.3"
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-skill
|
|
3
|
+
description: Add a new owned skill to theholocron/skills. INVOKE WHEN: user asks to create or add a new skill to the skills repo. Invoked as /holocron-skill-skill.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- editorconfig-checker-disable-file -->
|
|
7
|
+
|
|
8
|
+
# Add a new skill
|
|
9
|
+
|
|
10
|
+
Add a new owned skill to `theholocron/skills`.
|
|
11
|
+
|
|
12
|
+
Replace `<name>` with the skill's kebab-case identifier (e.g. `git-safety`, `holocron-skill-config`).
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. Decide the skill category
|
|
17
|
+
|
|
18
|
+
**Workflow & safety** — generic skills applicable to any repo (e.g. `git-safety`, `commit-standards`).
|
|
19
|
+
**Project-specific** — skills scoped to a particular theholocron repo or task (e.g. `holocron-skill-config`).
|
|
20
|
+
|
|
21
|
+
The category determines which section of `README.md` the skill is listed in.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. Create the skill file
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
skills/<name>/
|
|
29
|
+
└── SKILL.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### `SKILL.md` frontmatter
|
|
33
|
+
|
|
34
|
+
```markdown
|
|
35
|
+
---
|
|
36
|
+
name: <name>
|
|
37
|
+
description: <One-line description>. INVOKE WHEN: <trigger conditions>. Invoked as /<name>.
|
|
38
|
+
---
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `name` must match the directory name exactly.
|
|
42
|
+
- `description` is what Claude reads to decide whether to invoke the skill — make the "INVOKE WHEN" clause specific and unambiguous.
|
|
43
|
+
- "Invoked as `/<name>`" is the slash-command the user types.
|
|
44
|
+
|
|
45
|
+
### Body structure
|
|
46
|
+
|
|
47
|
+
Follow the pattern used by existing skills:
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
# <Skill title>
|
|
51
|
+
|
|
52
|
+
<One-paragraph summary of what this skill does and when to use it.>
|
|
53
|
+
|
|
54
|
+
## When to use
|
|
55
|
+
|
|
56
|
+
<Bullet list of specific trigger scenarios.>
|
|
57
|
+
|
|
58
|
+
## <Main content section(s)>
|
|
59
|
+
|
|
60
|
+
<Rules, checklists, file templates, etc.>
|
|
61
|
+
|
|
62
|
+
## Non-negotiables (if applicable)
|
|
63
|
+
|
|
64
|
+
<Hard rules the agent must never violate.>
|
|
65
|
+
|
|
66
|
+
## Checklist
|
|
67
|
+
|
|
68
|
+
<Numbered steps — the agent works through these in order.>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Keep it concise. The agent reads this at invocation time; every sentence should earn its place.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 3. Validate
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pnpm test
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The smoke test checks that every `skills/*/SKILL.md` exists. It will fail if the frontmatter is missing or the file is empty.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 4. Update `README.md`
|
|
86
|
+
|
|
87
|
+
Add a row to the **Owned skills** table in the appropriate section:
|
|
88
|
+
|
|
89
|
+
```markdown
|
|
90
|
+
| [`<name>`](./skills/<name>/SKILL.md) | <Short description — match the "description" frontmatter field> |
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
- Workflow & safety skills → "Workflow & safety" table
|
|
94
|
+
- Repo-specific skills → "Project-specific (theholocron)" table
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 5. Update `AGENTS.md`
|
|
99
|
+
|
|
100
|
+
Add a row to the **Available skills** table in the matching section:
|
|
101
|
+
|
|
102
|
+
```markdown
|
|
103
|
+
| `<name>` | <trigger phrase — a few words> |
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 6. Open a PR
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
git add skills/<name>/SKILL.md README.md AGENTS.md
|
|
112
|
+
git commit -s -m "feat: add <name> skill"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Semantic-release handles versioning. The `pnpm test` smoke test runs in CI.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Non-negotiables
|
|
120
|
+
|
|
121
|
+
- **`name` in frontmatter must match the directory name** — the smoke test and install tooling rely on this.
|
|
122
|
+
- **`INVOKE WHEN:` clause is required in `description`** — without it, the agent won't know when to invoke the skill automatically.
|
|
123
|
+
- **Both `README.md` and `AGENTS.md` must be updated** — `README.md` is the public-facing table; `AGENTS.md` is what agents read in consuming repos.
|
|
124
|
+
- **`pnpm test` must pass** before opening a PR.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Checklist
|
|
129
|
+
|
|
130
|
+
1. Create `skills/<name>/SKILL.md` with correct frontmatter and body.
|
|
131
|
+
2. Run `pnpm test` — smoke test must pass.
|
|
132
|
+
3. Add row to `README.md` owned skills table (correct section).
|
|
133
|
+
4. Add row to `AGENTS.md` Available skills table (correct section).
|
|
134
|
+
5. Open a PR with a `feat:` commit signed with `-s`.
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: holocron-skill-util
|
|
3
|
+
description: Scaffold a new @theholocron/<slug>-utils package in theholocron/utils. INVOKE WHEN: user asks to add a new utility package to the utils monorepo. Invoked as /holocron-skill-util.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- editorconfig-checker-disable-file -->
|
|
7
|
+
|
|
8
|
+
# Scaffold a new utility package
|
|
9
|
+
|
|
10
|
+
Scaffold a new `@theholocron/<name>-utils` package in `theholocron/utils`.
|
|
11
|
+
|
|
12
|
+
Replace `<name>` with the utility domain in kebab-case (e.g. `color`, `math`, `format`).
|
|
13
|
+
|
|
14
|
+
Reference implementations:
|
|
15
|
+
- Node-only package: `packages/string-utils` (canonical, no browser APIs)
|
|
16
|
+
- Browser-API package: `packages/location-utils` (adds DOM lib + eslint override)
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 1. Create the package directory
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
packages/<name>-utils/
|
|
24
|
+
├── src/
|
|
25
|
+
│ └── index.ts
|
|
26
|
+
├── package.json
|
|
27
|
+
├── tsdown.config.ts
|
|
28
|
+
├── tsconfig.json
|
|
29
|
+
├── vitest.config.ts
|
|
30
|
+
└── README.md
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Tests live colocated in `src/` as `*.test.ts` files alongside the source they cover.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 2. File templates
|
|
38
|
+
|
|
39
|
+
### `package.json`
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"name": "@theholocron/<name>-utils",
|
|
44
|
+
"version": "<current monorepo version>",
|
|
45
|
+
"description": "<One-line description.>",
|
|
46
|
+
"homepage": "https://github.com/theholocron/utils/tree/main/packages/<name>-utils#readme",
|
|
47
|
+
"bugs": "https://github.com/theholocron/utils/issues",
|
|
48
|
+
"releases": "https://github.com/theholocron/utils/releases",
|
|
49
|
+
"wiki": "https://github.com/theholocron/utils/wiki",
|
|
50
|
+
"repository": {
|
|
51
|
+
"type": "git",
|
|
52
|
+
"url": "git+https://github.com/theholocron/utils.git"
|
|
53
|
+
},
|
|
54
|
+
"license": "GPL-3.0",
|
|
55
|
+
"author": "Newton Koumantzelis",
|
|
56
|
+
"type": "module",
|
|
57
|
+
"exports": {
|
|
58
|
+
".": {
|
|
59
|
+
"import": "./dist/index.js",
|
|
60
|
+
"types": "./dist/index.d.ts"
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"files": ["dist", "README.md"],
|
|
64
|
+
"scripts": {
|
|
65
|
+
"build": "tsdown",
|
|
66
|
+
"lint": "eslint .",
|
|
67
|
+
"test": "vitest run",
|
|
68
|
+
"typecheck": "npx tsc --noEmit"
|
|
69
|
+
},
|
|
70
|
+
"devDependencies": {
|
|
71
|
+
"@theholocron/tsdown-config": "catalog:configs",
|
|
72
|
+
"@theholocron/vitest-config": "catalog:configs",
|
|
73
|
+
"@tsconfig/node-lts": "catalog:",
|
|
74
|
+
"@vitest/coverage-v8": "catalog:",
|
|
75
|
+
"tsdown": "catalog:",
|
|
76
|
+
"vitest": "catalog:"
|
|
77
|
+
},
|
|
78
|
+
"packageManager": "pnpm@10.34.4",
|
|
79
|
+
"engines": {
|
|
80
|
+
"node": ">=22",
|
|
81
|
+
"pnpm": ">=10"
|
|
82
|
+
},
|
|
83
|
+
"publishConfig": {
|
|
84
|
+
"access": "public"
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- **Match `version` to the current monorepo version** — check any existing package's `package.json`.
|
|
90
|
+
- Runtime dependencies (if any) go in `"dependencies"`, not `devDependencies`.
|
|
91
|
+
- Browser-API packages should add `"happy-dom": "catalog:"` to `devDependencies` for tests.
|
|
92
|
+
|
|
93
|
+
### `tsdown.config.ts`
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { library } from "@theholocron/tsdown-config/presets/library";
|
|
97
|
+
import type { UserConfig } from "tsdown";
|
|
98
|
+
|
|
99
|
+
const config: UserConfig = library({
|
|
100
|
+
deps: { neverBundle: [/^@theholocron\//] },
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
export default config;
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
If the package has runtime dependencies that should also be externalized, add their patterns to `neverBundle` (e.g. `packages/string-utils` externalizes `change-case` and `title-case`).
|
|
107
|
+
|
|
108
|
+
### `tsconfig.json` (Node-only)
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"display": "<Name> Utilities",
|
|
113
|
+
"extends": "@tsconfig/node-lts/tsconfig.json",
|
|
114
|
+
"compilerOptions": {
|
|
115
|
+
"allowImportingTsExtensions": true
|
|
116
|
+
},
|
|
117
|
+
"include": ["./src/**/*.ts"],
|
|
118
|
+
"exclude": ["./node_modules", "**/*.test.ts"]
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### `tsconfig.json` (Browser-API package)
|
|
123
|
+
|
|
124
|
+
Add `"lib"` to `compilerOptions`:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"display": "<Name> Utilities",
|
|
129
|
+
"extends": "@tsconfig/node-lts/tsconfig.json",
|
|
130
|
+
"compilerOptions": {
|
|
131
|
+
"allowImportingTsExtensions": true,
|
|
132
|
+
"lib": ["dom", "dom.iterable", "es2022"]
|
|
133
|
+
},
|
|
134
|
+
"include": ["./src/**/*.ts"],
|
|
135
|
+
"exclude": ["./node_modules", "**/*.test.ts"]
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### `vitest.config.ts`
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
import { library } from "@theholocron/vitest-config/bundles/library";
|
|
143
|
+
import { defineConfig } from "vitest/config";
|
|
144
|
+
|
|
145
|
+
export default defineConfig(library({ globals: true }) as never);
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`globals: true` is required — tests use `describe`/`test`/`expect` without explicit imports.
|
|
149
|
+
|
|
150
|
+
### `src/index.ts`
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
// Named exports — no default export
|
|
154
|
+
export function myUtil(value: string): string {
|
|
155
|
+
return value;
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Use named exports throughout. Group related utilities into sibling files (`src/casing.ts`, `src/casting.ts`, …) and re-export from `src/index.ts`:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
export * from "./casing.ts";
|
|
163
|
+
export * from "./casting.ts";
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Note: source imports use `.ts` extensions — TypeScript's ESM convention.
|
|
167
|
+
|
|
168
|
+
### Test files (`src/<module>.test.ts`)
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
import { describe, expect, test } from "vitest";
|
|
172
|
+
|
|
173
|
+
import { myUtil } from "./index.ts";
|
|
174
|
+
|
|
175
|
+
describe("<Name>", () => {
|
|
176
|
+
test("does X", () => {
|
|
177
|
+
expect(myUtil("input")).toBe("expected");
|
|
178
|
+
});
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### `README.md`
|
|
183
|
+
|
|
184
|
+
```markdown
|
|
185
|
+
# `@theholocron/<name>-utils`
|
|
186
|
+
|
|
187
|
+
<One-line description of what the utilities do.>
|
|
188
|
+
|
|
189
|
+
## Installation
|
|
190
|
+
|
|
191
|
+
\`\`\`bash
|
|
192
|
+
pnpm add @theholocron/<name>-utils
|
|
193
|
+
\`\`\`
|
|
194
|
+
|
|
195
|
+
## Usage
|
|
196
|
+
|
|
197
|
+
\`\`\`typescript
|
|
198
|
+
import * as <name> from "@theholocron/<name>-utils";
|
|
199
|
+
|
|
200
|
+
<minimal working example>
|
|
201
|
+
\`\`\`
|
|
202
|
+
|
|
203
|
+
## Documentation
|
|
204
|
+
|
|
205
|
+
Check out [The Holocron Archive](https://docs.theholocron.dev/projects/utils/) for more information.
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 3. Register in `release.config.ts`
|
|
211
|
+
|
|
212
|
+
Add the new package path to `prepareCmd` **in alphabetical order**:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
// release.config.ts
|
|
216
|
+
"node -e \"...['packages/array-utils','packages/<name>-utils',...].forEach(...)\"",
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 4. Add to `codecov.yml`
|
|
222
|
+
|
|
223
|
+
Append to `component_management.individual_components` (keep alphabetical):
|
|
224
|
+
|
|
225
|
+
```yaml
|
|
226
|
+
- component_id: <name>-utils
|
|
227
|
+
name: "<name>-utils"
|
|
228
|
+
paths:
|
|
229
|
+
- packages/<name>-utils/**
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## 5. Browser-API packages only: update root `eslint.config.ts`
|
|
235
|
+
|
|
236
|
+
Add the new package's source path to the browser override block:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
// eslint.config.ts — existing override
|
|
240
|
+
files: [
|
|
241
|
+
"packages/location-utils/src/**",
|
|
242
|
+
"packages/misc-utils/src/**",
|
|
243
|
+
"packages/storage-utils/src/**",
|
|
244
|
+
"packages/<name>-utils/src/**", // ← add here
|
|
245
|
+
],
|
|
246
|
+
rules: {
|
|
247
|
+
"n/no-unsupported-features/node-builtins": "off",
|
|
248
|
+
},
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Non-negotiables
|
|
254
|
+
|
|
255
|
+
- **`catalog:configs`** for `@theholocron/tsdown-config` and `@theholocron/vitest-config`; `catalog:` for everything else — never pin exact versions.
|
|
256
|
+
- **`tsdown` and `vitest` must be direct `devDependencies`** — pnpm does not expose transitive binaries.
|
|
257
|
+
- **`globals: true`** in every `vitest.config.ts` — required by existing test style.
|
|
258
|
+
- **Match version to current monorepo version** before opening a PR.
|
|
259
|
+
- **Run `pnpm install`** after adding `package.json` to pick up workspace resolution.
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Checklist
|
|
264
|
+
|
|
265
|
+
1. Create `packages/<name>-utils/` with all files listed above.
|
|
266
|
+
2. Add package path to `prepareCmd` in `release.config.ts` (alphabetical order).
|
|
267
|
+
3. Add `component_id` entry to `codecov.yml` (alphabetical order).
|
|
268
|
+
4. If browser-API package: add `"lib"` to tsconfig + add path to root `eslint.config.ts` override.
|
|
269
|
+
5. Run `pnpm install` — must resolve without errors.
|
|
270
|
+
6. Run `pnpm build` — tsdown must compile successfully.
|
|
271
|
+
7. Run `pnpm test` — all tests must pass.
|
|
272
|
+
8. Run `pnpm typecheck` — no type errors.
|
|
273
|
+
9. Run `pnpm lint` — no lint errors.
|
|
274
|
+
10. Open a PR with a `feat:` commit — semantic-release computes a minor bump and publishes all packages in lockstep.
|