@theholocron/skills 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Newton Koumantzelis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,108 @@
1
+ # `@theholocron/skills`
2
+
3
+ <!-- holocron:description -->
4
+
5
+ Shared agent skill registry.
6
+
7
+ <!-- /holocron:description -->
8
+
9
+ Each skill is a directory under `skills/` containing a `SKILL.md` file that Claude Code (and compatible
10
+ agents) can load as a slash command.
11
+
12
+ ## Owned skills
13
+
14
+ Skills authored and maintained in this repo. Published inside the npm package.
15
+
16
+ ### Workflow & safety
17
+
18
+ | Skill | Description |
19
+ |-------|-------------|
20
+ | [`git-safety`](./skills/git-safety/SKILL.md) | Never force-push or run destructive git ops without permission |
21
+ | [`pr-workflow`](./skills/pr-workflow/SKILL.md) | Always open a PR; one-change-per-PR; delete branch on close |
22
+ | [`commit-standards`](./skills/commit-standards/SKILL.md) | Conventional Commits format + DCO signing |
23
+ | [`security-review`](./skills/security-review/SKILL.md) | OWASP-oriented checklist for code review |
24
+
25
+ ### Project-specific (theholocron)
26
+
27
+ | Skill | Description |
28
+ |-------|-------------|
29
+ | [`holocron-skill-config`](./skills/holocron-skill-config/SKILL.md) | Scaffold a new `@theholocron/*-config` package in `theholocron/configs` |
30
+ | [`holocron-skill-client`](./skills/holocron-skill-client/SKILL.md) | Scaffold a new `@theholocron/*-client` package in `theholocron/clients` |
31
+ | [`holocron-skill-plugin`](./skills/holocron-skill-plugin/SKILL.md) | Scaffold or migrate a new `holocron-plugin-*` package |
32
+
33
+ ## External skills
34
+
35
+ Tracked in [`skills-lock.json`](./skills-lock.json) with source provenance and content hash.
36
+ Not committed to this repo — fetched from upstream by `holocron skills update` (planned).
37
+
38
+ | Skill | Source | Description |
39
+ |-------|--------|-------------|
40
+ | `find-skills` | [vercel-labs/skills](https://github.com/vercel-labs/skills) | Discover and install agent skills from the skills.sh ecosystem |
41
+ | `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) | Distinctive, intentional UI design guidance |
42
+ | `vercel-cli` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Vercel CLI: deploy, env vars, logs, domains, project linking |
43
+ | `turbopack` | [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) | Turbopack bundler: HMR, CSS, tree shaking, webpack migration |
44
+
45
+ ## Installation via `holocron setup`
46
+
47
+ Skills are installed by `holocron setup` based on the `skills` field in
48
+ `holocron.config.ts`. They are written to `.agents/skills/<name>/` with a
49
+ symlink at the agent-specific path, and **gitignored** — treated as dependencies,
50
+ not source.
51
+
52
+ ```typescript
53
+ // holocron.config.ts
54
+ import { defineConfig } from "@theholocron/cli";
55
+
56
+ export default defineConfig({
57
+ agent: "claude",
58
+ skills: ["git-safety", "pr-workflow", "commit-standards", "security-review"],
59
+ // ...
60
+ });
61
+ ```
62
+
63
+ Then run:
64
+
65
+ ```sh
66
+ pnpm add -D @theholocron/skills
67
+ GITHUB_TOKEN=$(gh auth token) pnpm exec holocron setup
68
+ ```
69
+
70
+ ## Manual installation
71
+
72
+ Copy a skill directory into your project's `.agents/skills/` and symlink it:
73
+
74
+ ```sh
75
+ cp -r node_modules/@theholocron/skills/skills/git-safety .agents/skills/
76
+ ln -s ../../.agents/skills/git-safety .claude/skills/git-safety
77
+ ```
78
+
79
+ Add both to `.gitignore`:
80
+
81
+ ```gitignore
82
+ # managed by holocron setup — skills
83
+ /.agents/skills/
84
+ /.claude/skills/git-safety
85
+ ```
86
+
87
+ ## Contributing
88
+
89
+ ### Adding an owned skill
90
+
91
+ 1. Create `skills/<name>/SKILL.md` with the frontmatter format:
92
+ ```markdown
93
+ ---
94
+ name: <name>
95
+ description: One-line description. INVOKE WHEN: <trigger conditions>.
96
+ ---
97
+ # skill title
98
+ …
99
+ ```
100
+ 2. Run `pnpm test` — the smoke test checks that every skill dir has a `SKILL.md`.
101
+ 3. Update this README with a row in the owned skills table.
102
+ 4. Open a PR with a `feat:` commit — semantic-release handles versioning.
103
+
104
+ ### Registering an external skill
105
+
106
+ Run `npx skills add <repo> --skill <name>` from this repo root. This records the
107
+ skill in `skills-lock.json` with its source and content hash but does **not** copy
108
+ it into `skills/` — external skill content is fetched at install time.
package/package.json ADDED
@@ -0,0 +1,58 @@
1
+ {
2
+ "name": "@theholocron/skills",
3
+ "version": "1.0.0",
4
+ "description": "Shared agent skill registry.",
5
+ "keywords": [
6
+ "agent",
7
+ "claude",
8
+ "codex",
9
+ "developer-tools",
10
+ "skills",
11
+ "theholocron"
12
+ ],
13
+ "homepage": "https://github.com/theholocron/skills#readme",
14
+ "bugs": "https://github.com/theholocron/skills/issues",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/theholocron/skills.git"
18
+ },
19
+ "license": "MIT",
20
+ "author": "Newton Koumantzelis",
21
+ "type": "module",
22
+ "exports": {
23
+ "./package.json": "./package.json",
24
+ "./skills/*": "./skills/*"
25
+ },
26
+ "files": [
27
+ "skills/",
28
+ "skills-lock.json",
29
+ "README.md"
30
+ ],
31
+ "devDependencies": {
32
+ "@commitlint/cli": "^21.2.1",
33
+ "@commitlint/config-conventional": "^21.2.0",
34
+ "@commitlint/types": "^21.2.0",
35
+ "@semantic-release/changelog": "^6.0.3",
36
+ "@semantic-release/exec": "^7.1.0",
37
+ "@semantic-release/git": "^10.0.1",
38
+ "@semantic-release/github": "^12.0.9",
39
+ "@theholocron/cli": ">=2.0.0-alpha.0 <2.0.0",
40
+ "@theholocron/commitlint-config": "^7.3.1",
41
+ "@theholocron/holocron-plugin-github": ">=2.0.0-alpha.0 <2.0.0",
42
+ "@theholocron/semantic-release-config": "^7.3.1",
43
+ "conventional-changelog-conventionalcommits": "^10.2.1",
44
+ "semantic-release": "^25.0.7"
45
+ },
46
+ "engines": {
47
+ "node": ">=22",
48
+ "pnpm": ">=10"
49
+ },
50
+ "publishConfig": {
51
+ "access": "public"
52
+ },
53
+ "releases": "https://github.com/theholocron/skills/releases",
54
+ "wiki": "https://github.com/theholocron/skills/wiki",
55
+ "scripts": {
56
+ "test": "node --test test/index.mjs"
57
+ }
58
+ }
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: commit-standards
3
+ description: Commit message standards. INVOKE WHEN: writing a commit message, reviewing a commit, opening a PR. Always use Conventional Commits and sign commits with -s (DCO).
4
+ ---
5
+
6
+ # commit standards
7
+
8
+ ## Conventional Commits
9
+
10
+ All commit subjects must follow the Conventional Commits format:
11
+
12
+ ```
13
+ <type>[optional scope]: <description>
14
+ ```
15
+
16
+ ### Types
17
+
18
+ | Type | Use for |
19
+ |------|---------|
20
+ | `feat` | New feature (triggers minor version bump) |
21
+ | `fix` | Bug fix (triggers patch bump) |
22
+ | `chore` | Maintenance that doesn't affect published artifacts |
23
+ | `docs` | Documentation-only changes |
24
+ | `ci` | CI/workflow changes (won't appear in changelog) |
25
+ | `test` | Test additions or changes |
26
+ | `refactor` | Code restructuring with no behavior change |
27
+ | `perf` | Performance improvement |
28
+
29
+ ### Breaking changes
30
+
31
+ Append `!` after the type/scope, or add `BREAKING CHANGE:` in the footer:
32
+
33
+ ```
34
+ feat!: remove deprecated auth endpoint
35
+
36
+ BREAKING CHANGE: the /v1/auth endpoint has been removed; use /v2/auth
37
+ ```
38
+
39
+ ## DCO — always `git commit -s`
40
+
41
+ The `Signed-off-by:` trailer is required on every commit in theholocron repos.
42
+ The `-s` flag generates it automatically from your git config:
43
+
44
+ ```sh
45
+ git commit -s -m "feat: add new thing"
46
+ ```
47
+
48
+ Result:
49
+ ```
50
+ feat: add new thing
51
+
52
+ Signed-off-by: Your Name <you@example.com>
53
+ ```
54
+
55
+ Never skip `-s`. Branch protection and CI enforce DCO.
56
+
57
+ ## No agent attribution
58
+
59
+ Do not add `Co-Authored-By: Claude` or any agent attribution in commits, PRs,
60
+ issues, or docs. The author is always the user.
61
+
62
+ ## Commit scope
63
+
64
+ Keep commits focused. One logical change per commit makes history bisectable and
65
+ makes semantic-release versioning accurate.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: git-safety
3
+ description: Git safety rules. INVOKE WHEN: git push, force push, git reset, git clean, destructive git operations. NEVER force push or do destructive git operations without explicit permission.
4
+ ---
5
+
6
+ # git safety
7
+
8
+ ## rules
9
+
10
+ - NEVER force push (`git push --force` or `git push -f`)
11
+ - NEVER `git reset --hard` without explicit user permission
12
+ - NEVER `git clean -fd` without explicit user permission
13
+ - NEVER `git checkout -- .` (discards all changes) without explicit user permission
14
+ - Prefer `git stash` over `git reset` to save work before switching context
15
+ - Always `git pull` (or `git fetch` + rebase) before `git push`
16
+
17
+ ## forbidden commands
18
+
19
+ These require EXPLICIT user permission before running:
20
+
21
+ - `git push --force`
22
+ - `git push -f`
23
+ - `git push --force-with-lease`
24
+ - `git reset --hard`
25
+ - `git clean -fd`
26
+ - `git checkout -- .`
27
+
28
+ If you find yourself about to run one of these, stop and ask the user first.
29
+
30
+ ## safe alternatives
31
+
32
+ **Instead of `git reset --hard`:**
33
+ - `git stash` to save changes temporarily
34
+ - `git stash pop` to restore them later
35
+
36
+ **Instead of force push:**
37
+ - `git pull --rebase` then normal push to reconcile diverged history
38
+ - If history is intentionally diverged, stop and ask the user how they want to proceed
39
+
40
+ **Instead of `git clean -fd`:**
41
+ - `git stash --include-untracked` to preserve files
42
+ - Review untracked files with `git status` before deciding to delete
43
+
44
+ ## standard workflow
45
+
46
+ 1. `git pull` (or `git fetch && git rebase origin/main`) before making changes
47
+ 2. Create a branch: `git checkout -b <type>/<description>`
48
+ 3. Make changes, then `git add <specific-files>` (never `git add -A` carelessly)
49
+ 4. `git commit -s` (DCO required in theholocron repos)
50
+ 5. `git pull --rebase` again before push to catch any upstream changes
51
+ 6. `git push -u origin <branch>` (no force flags)
52
+ 7. Open a PR — never push directly to the default branch
@@ -0,0 +1,151 @@
1
+ ---
2
+ name: holocron-skill-client
3
+ description: Scaffold a new @theholocron/<slug>-client package in theholocron/clients. INVOKE WHEN: user asks to add a new HTTP client package to the clients monorepo. Invoked as /holocron-skill-client.
4
+ ---
5
+
6
+ <!-- editorconfig-checker-disable-file -->
7
+
8
+ # Scaffold a new client package
9
+
10
+ Replace `<slug>` with the vendor name in kebab-case (e.g. `slack`, `stripe`),
11
+ `<Vendor>` with PascalCase (e.g. `Slack`, `Stripe`), and `<BASE_URL>` with
12
+ the API root (e.g. `https://api.stripe.com`).
13
+
14
+ Reference implementation: `packages/zendesk-client` (the canonical example
15
+ of the current patterns — `createRestClient`, `stubFetch`, DI fetch).
16
+
17
+ ---
18
+
19
+ ## 1. Register in the workspace
20
+
21
+ Add to `pnpm-workspace.yaml`:
22
+
23
+ ```yaml
24
+ packages:
25
+ - packages/<slug>-client
26
+ ```
27
+
28
+ Then run `pnpm install` from the repo root.
29
+
30
+ ---
31
+
32
+ ## 2. Config files (identical across all clients)
33
+
34
+ **`packages/<slug>-client/package.json`**
35
+
36
+ ```json
37
+ {
38
+ "name": "@theholocron/<slug>-client",
39
+ "version": "0.0.0",
40
+ "description": "A TypeScript client for the <Vendor> API",
41
+ "homepage": "https://github.com/theholocron/clients/tree/main/packages/<slug>-client#readme",
42
+ "bugs": "https://github.com/theholocron/clients/issues",
43
+ "repository": {
44
+ "type": "git",
45
+ "url": "git+https://github.com/theholocron/clients.git",
46
+ "directory": "packages/<slug>-client"
47
+ },
48
+ "license": "GPL-3.0",
49
+ "author": "Newton Koumantzelis",
50
+ "type": "module",
51
+ "main": "./src/index.ts",
52
+ "exports": { ".": "./src/index.ts" },
53
+ "scripts": {
54
+ "build": "tsdown",
55
+ "lint": "eslint .",
56
+ "test": "vitest run",
57
+ "test:watch": "vitest",
58
+ "test:coverage": "vitest run --coverage",
59
+ "typecheck": "tsc --noEmit"
60
+ },
61
+ "dependencies": {
62
+ "@theholocron/http-client": "<current-lockstep-version>"
63
+ },
64
+ "devDependencies": {
65
+ "@types/node": "^22.0.0",
66
+ "@theholocron/eslint-config": "catalog:",
67
+ "@theholocron/tsconfig": "catalog:",
68
+ "@theholocron/tsdown-config": "catalog:",
69
+ "@theholocron/vitest-config": "catalog:",
70
+ "@vitest/coverage-v8": "catalog:",
71
+ "@vitest/eslint-plugin": "catalog:",
72
+ "eslint": "catalog:",
73
+ "eslint-plugin-n": "catalog:",
74
+ "globals": "catalog:",
75
+ "tsdown": "catalog:",
76
+ "typescript": "catalog:",
77
+ "vitest": "catalog:"
78
+ },
79
+ "publishConfig": {
80
+ "access": "public",
81
+ "main": "./dist/index.mjs",
82
+ "types": "./dist/index.d.mts",
83
+ "exports": {
84
+ ".": {
85
+ "types": "./dist/index.d.mts",
86
+ "import": "./dist/index.mjs",
87
+ "default": "./dist/index.mjs"
88
+ }
89
+ }
90
+ },
91
+ "files": ["dist", "README.md"],
92
+ "engines": { "node": ">=22.0.0" },
93
+ "releases": "https://github.com/theholocron/clients/releases"
94
+ }
95
+ ```
96
+
97
+ ## 3. Source files
98
+
99
+ ### `src/client.ts` — REST client factory
100
+
101
+ ```ts
102
+ import { createRestClient, type RestClient } from "@theholocron/http-client";
103
+
104
+ export interface <Vendor>ClientOptions {
105
+ token: string;
106
+ fetch?: typeof fetch;
107
+ }
108
+
109
+ export function create<Vendor>RestClient(opts: <Vendor>ClientOptions): RestClient {
110
+ return createRestClient({
111
+ baseUrl: "<BASE_URL>",
112
+ token: opts.token,
113
+ vendor: "<Vendor>",
114
+ fetch: opts.fetch,
115
+ });
116
+ }
117
+ ```
118
+
119
+ ### `src/index.ts` — factory + public API
120
+
121
+ ```ts
122
+ import { create<Vendor>RestClient } from "./client.js";
123
+ import { <resources> } from "./<resources>.js";
124
+
125
+ export type { <Vendor>ClientOptions } from "./client.js";
126
+ export type * from "./types.js";
127
+
128
+ export function create<Vendor>Client(opts: <Vendor>ClientOptions) {
129
+ const rest = create<Vendor>RestClient(opts);
130
+ return { <resources>: <resources>(rest) };
131
+ }
132
+ ```
133
+
134
+ ## 4. Non-negotiables
135
+
136
+ 1. **Add to `.releaserc.json` `prepareCmd`** — alphabetical order. Omitting this leaves
137
+ the package frozen at its initial version while all others advance.
138
+ 2. **Set initial `version`** in `package.json` to match the current lockstep version.
139
+ 3. **Add entry to `codecov.yml`** under `component_management.individual_components`.
140
+ 4. **Use `stubFetch`** in tests — DI pattern, no `vi.stubGlobal`.
141
+
142
+ ## 5. Checklist before opening a PR
143
+
144
+ - [ ] `pnpm install` — workspace symlink created
145
+ - [ ] `pnpm --filter @theholocron/<slug>-client typecheck` passes
146
+ - [ ] `pnpm --filter @theholocron/<slug>-client lint` passes
147
+ - [ ] `pnpm --filter @theholocron/<slug>-client test` passes
148
+ - [ ] `pnpm --filter @theholocron/<slug>-client build` — `dist/` emitted
149
+ - [ ] `packages/<slug>-client` added to `prepareCmd` in `.releaserc.json`
150
+ - [ ] `version` in `package.json` set to current lockstep version
151
+ - [ ] `codecov.yml` entry added
@@ -0,0 +1,145 @@
1
+ ---
2
+ name: holocron-skill-config
3
+ description: Scaffold a new shareable config package in theholocron/configs. INVOKE WHEN: user asks to add a new @theholocron/<tool>-config package to the configs monorepo. Invoked as /holocron-skill-config.
4
+ ---
5
+
6
+ <!-- editorconfig-checker-disable-file -->
7
+
8
+ # Scaffold a new config package
9
+
10
+ Scaffold a new shareable config package in `theholocron/configs`.
11
+
12
+ ## When to use
13
+
14
+ When the user asks to add a new `@theholocron/<tool>-config` package to this monorepo.
15
+
16
+ ## What to produce
17
+
18
+ Seven files in `packages/<tool>-config/`:
19
+
20
+ ```
21
+ packages/<tool>-config/
22
+ ├── package.json
23
+ ├── index.js (or named-export entry; use bundles/ for multi-preset)
24
+ └── README.md
25
+ ```
26
+
27
+ Optionally, if the config needs multiple presets:
28
+
29
+ ```
30
+ packages/<tool>-config/
31
+ ├── package.json
32
+ ├── index.js (re-exports all named presets)
33
+ ├── presets/
34
+ │ ├── node.js
35
+ │ └── react.js
36
+ ├── bundles/ (preset + opinionated settings combined)
37
+ │ └── library.js
38
+ └── README.md
39
+ ```
40
+
41
+ ## File templates
42
+
43
+ ### `package.json`
44
+
45
+ Copy the shape from an existing package (e.g. `packages/vitest-config/package.json`).
46
+ Key fields:
47
+
48
+ ```json
49
+ {
50
+ "name": "@theholocron/<tool>-config",
51
+ "version": "4.1.0",
52
+ "description": "A <Tool> configuration for <purpose>.",
53
+ "homepage": "https://github.com/theholocron/configs/tree/main/packages/<tool>-config#readme",
54
+ "bugs": "https://github.com/theholocron/configs/issues",
55
+ "repository": {
56
+ "type": "git",
57
+ "url": "git+https://github.com/theholocron/configs.git"
58
+ },
59
+ "license": "GPL-3.0",
60
+ "author": "Newton Koumantzelis",
61
+ "type": "module",
62
+ "exports": {
63
+ ".": { "import": "./index.js", "default": "./index.js" }
64
+ },
65
+ "files": ["index.js"],
66
+ "peerDependencies": {
67
+ "<tool>": "^<major>"
68
+ },
69
+ "publishConfig": { "access": "public" }
70
+ }
71
+ ```
72
+
73
+ - Match `version` to the current monorepo version (check the root `package.json`).
74
+ - All peer deps that are optional per-preset go under `peerDependenciesMeta`:
75
+ ```json
76
+ "peerDependenciesMeta": { "<tool>": { "optional": true } }
77
+ ```
78
+ - Export each preset/bundle as a subpath (`"./presets/node"`, `"./bundles/library"`, …)
79
+ and add those to `"files"`.
80
+
81
+ ### `index.js` (single-export example)
82
+
83
+ ```js
84
+ /**
85
+ * @see https://example.com/docs/config
86
+ * @type {import("<tool>").Config}
87
+ */
88
+ const config = {
89
+ // ...
90
+ };
91
+
92
+ export default config;
93
+ ```
94
+
95
+ ### `index.js` (multi-export / named presets)
96
+
97
+ ```js
98
+ export { node } from "./presets/node.js";
99
+ export { react } from "./presets/react.js";
100
+ ```
101
+
102
+ ### `README.md`
103
+
104
+ Follow this structure (see existing READMEs for tone):
105
+
106
+ ```markdown
107
+ # <Tool> Config
108
+
109
+ A [<Tool> configuration](official-docs-url) for <one-line description>.
110
+
111
+ ## Installation
112
+
113
+ \`\`\`bash
114
+ npm install --save-dev @theholocron/<tool>-config
115
+ \`\`\`
116
+
117
+ ## Usage
118
+
119
+ <minimal working example — show the exact file name the user creates and its contents>
120
+
121
+ ## <Optional: named presets or bundles section>
122
+ ```
123
+
124
+ Keep it short. Link to official docs rather than duplicating them.
125
+
126
+ ## Non-negotiables
127
+
128
+ - **No build step.** Source JS is the published artifact. Do not add TypeScript
129
+ compilation.
130
+ - **Match version to current monorepo version** — check root `package.json`.
131
+ - **Peer deps, not regular deps.** The tool being configured belongs in
132
+ `peerDependencies`.
133
+ - **Deprecation notice** if replacing an existing package — add a banner at the
134
+ top of the old package's `README.md` pointing to the replacement.
135
+ - Run `pnpm install` after adding the package to pick up workspace resolution.
136
+ - Run `pnpm lint` to verify the new files pass ESLint.
137
+
138
+ ## Checklist
139
+
140
+ 1. Create `packages/<tool>-config/` with `package.json`, `index.js`, `README.md`
141
+ 2. Add `vitest` and `@theholocron/vitest-config: "workspace:*"` to `devDependencies`
142
+ 3. Add `"build": "tsdown"`, `"test": "vitest run"`, `"typecheck": "tsc --noEmit"` to scripts
143
+ 4. Add entry to `codecov.yml` under `component_management.individual_components`
144
+ 5. Verify `pnpm install` resolves, `pnpm build` succeeds, `pnpm test` passes
145
+ 6. Open a PR with a `feat:` commit
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: holocron-skill-plugin
3
+ description: Scaffold a new @theholocron/holocron-plugin-<slug> package. INVOKE WHEN: user asks to add a new provider plugin to theholocron/holocron. Since v2.0.0-alpha, use the CLI command instead. Invoked as /holocron-skill-plugin.
4
+ ---
5
+
6
+ <!-- editorconfig-checker-disable-file -->
7
+
8
+ # Scaffold a new holocron plugin
9
+
10
+ Since v2.0.0-alpha, plugin scaffolding is a first-class CLI command.
11
+ Skip this skill; run:
12
+
13
+ ```bash
14
+ pnpm holocron plugin create <slug> <vendor> \
15
+ --capability <key> \
16
+ --vendor-env <VENDOR_NATIVE_ENV_NAME> \
17
+ --base-url <https://api.vendor.example>
18
+ ```
19
+
20
+ The command produces 18 files under `packages/holocron-plugin-<slug>/`
21
+ matching the same template this skill used to hand-craft:
22
+
23
+ - 5 config files (`package.json`, `tsconfig.json`, `vitest.config.ts`,
24
+ `eslint.config.js`, `tsdown.config.ts`)
25
+ - 1 `README.md`
26
+ - 5 source files (`auth.ts` with 4-step keyring precedence, `rest.ts`,
27
+ `verify-token.ts`, `index.ts` with `AUTH_HINT` export,
28
+ `capabilities/<key>.ts` stub)
29
+ - 6 test files (`helpers.ts`, `auth.test.ts`, `rest.test.ts`,
30
+ `verify-token.test.ts`, `<key>.test.ts` with `it.todo`,
31
+ `index.test.ts`)
32
+ - 1 validation script (`scripts/validate.mjs`)
33
+
34
+ Then follow the "Next" steps printed by the command:
35
+
36
+ 1. `pnpm install`
37
+ 2. `pnpm --filter @theholocron/holocron-plugin-<slug> typecheck lint test`
38
+ 3. Fill in the `<VendorName><Capability>` class methods against the
39
+ capability interface in `packages/cli/src/capabilities/index.ts`.
40
+ 4. Replace `it.todo(...)` with real tests.
41
+ 5. Commit + push when the capability is functionally complete.
42
+ 6. **Wire a typed client** once `@theholocron/<slug>-client` exists.
43
+
44
+ ## Step 6: migrate to a typed client
45
+
46
+ The scaffolded `rest.ts` uses the raw `createRestClient` from `@theholocron/cli`.
47
+ Once a typed client package exists in `theholocron/clients`, replace it:
48
+
49
+ **`src/rest.ts`** — swap to a re-export:
50
+
51
+ ```ts
52
+ export {
53
+ create<Vendor>Client,
54
+ type <Vendor>Client,
55
+ type <Vendor>ClientOptions,
56
+ } from "@theholocron/<slug>-client";
57
+ ```
58
+
59
+ **`pnpm-workspace.yaml` catalog + plugin `package.json`:**
60
+
61
+ ```yaml
62
+ # pnpm-workspace.yaml
63
+ catalog:
64
+ "@theholocron/<slug>-client": ^<version>
65
+ ```
66
+
67
+ ```json
68
+ "peerDependencies": { "@theholocron/<slug>-client": "catalog:" },
69
+ "peerDependenciesMeta": { "@theholocron/<slug>-client": { "optional": false } },
70
+ "devDependencies": { "@theholocron/<slug>-client": "catalog:" }
71
+ ```
72
+
73
+ ## Auth pattern (4-step precedence)
74
+
75
+ Every plugin's `auth.ts` follows this order:
76
+ 1. `--token` CLI flag (`RuntimeContext.cliToken`)
77
+ 2. `HOLOCRON_<VENDOR>_TOKEN` env var
78
+ 3. `<VENDOR_NATIVE_ENV_VAR>` env var
79
+ 4. Keyring lookup → `AuthError` if all fail
80
+
81
+ ## Design references
82
+
83
+ - `.notes/tool-plugin-create.spec.md` — CLI scaffolding spec
84
+ - `.notes/tech-auth-bootstrap.spec.md` — 4-step token precedence
85
+ - `.notes/tech-vault-choice.spec.md` — Doppler + Infisical adoption
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: pr-workflow
3
+ description: Pull request workflow rules. INVOKE WHEN: opening a PR, merging, closing a PR, creating a branch. Always open a PR — never push directly to the default branch.
4
+ ---
5
+
6
+ # PR workflow
7
+
8
+ ## core rules
9
+
10
+ - **Always open a PR — never push directly to the default branch.** Even for
11
+ small fixes: create a branch, push it, open a PR. This lets CI run, keeps
12
+ history reviewable, and respects branch protection. The only exception is
13
+ bootstrapping a brand-new repo before protection is set up.
14
+ - **One PR = one focused change.** Squash-merge; the PR title becomes the
15
+ squashed commit subject that semantic-release reads.
16
+ - **File issues for non-trivial work** and reference them in commits/PRs
17
+ (`Closes #N` / `Refs #N`). Skip for typo fixes.
18
+
19
+ ## opening a PR
20
+
21
+ 1. Create a branch from the correct base (usually `main`; `alpha` in holocron)
22
+ 2. Push the branch: `git push -u origin <branch>`
23
+ 3. Open the PR with `gh pr create` — title = squashed commit subject (Conventional Commit format)
24
+ 4. Reference any related issues in the body
25
+
26
+ ## merging
27
+
28
+ - Squash-merge only — the PR title becomes the single commit on the base branch
29
+ - The merge commit subject must follow Conventional Commits so semantic-release
30
+ can compute the correct version bump
31
+
32
+ ## closing / discarding
33
+
34
+ **Delete the branch when closing, never just close the PR.** A closed-but-existing
35
+ branch blocks future PR creation for the same branch name — GitHub returns 422
36
+ "A pull request already exists" and the sync silently skips opening a new one.
37
+
38
+ ```sh
39
+ gh pr close <n> --repo <owner>/<repo> --delete-branch
40
+ ```
41
+
42
+ ## bad sync PRs
43
+
44
+ If a workflow-sync PR is stale or wrong, use the command above. Do NOT close the
45
+ PR without deleting the branch or the next sync run will silently fail.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: security-review
3
+ description: Security review checklist. INVOKE WHEN: reviewing code for security issues, auditing a PR, checking for vulnerabilities. Check for OWASP top 10 and common Node.js/TypeScript security pitfalls.
4
+ ---
5
+
6
+ # security review
7
+
8
+ ## checklist
9
+
10
+ Run through these for any code that handles user input, authentication, secrets,
11
+ or network requests.
12
+
13
+ ### injection
14
+
15
+ - [ ] No SQL built with string concatenation — use parameterized queries
16
+ - [ ] No shell commands built from user input — avoid `exec`/`spawn` with interpolated strings
17
+ - [ ] No `eval()` or `new Function()` with user-controlled strings
18
+ - [ ] Template literals used in shell commands are sanitized
19
+
20
+ ### authentication and secrets
21
+
22
+ - [ ] Secrets loaded from environment variables, never hardcoded
23
+ - [ ] No secrets in log output (even at debug level)
24
+ - [ ] No secrets committed to git (check `.env*`, config files, test fixtures)
25
+ - [ ] Tokens/credentials not stored in `localStorage` or cookies without `httpOnly`/`Secure`
26
+
27
+ ### input validation
28
+
29
+ - [ ] All external input validated at the boundary (HTTP body, CLI args, env vars)
30
+ - [ ] File paths from user input sanitized against path traversal (`../`)
31
+ - [ ] File uploads restricted by type and size
32
+
33
+ ### dependencies
34
+
35
+ - [ ] `pnpm audit` passes (no critical/high vulnerabilities)
36
+ - [ ] New dependencies are from reputable sources with active maintenance
37
+ - [ ] Avoid dependencies that do too much (bloated attack surface)
38
+
39
+ ### output / XSS
40
+
41
+ - [ ] User content rendered in HTML is escaped (no `dangerouslySetInnerHTML` with unsanitized input)
42
+ - [ ] Content-Security-Policy headers set where applicable
43
+
44
+ ### Node.js specific
45
+
46
+ - [ ] `child_process` calls use the array form of `exec`/`spawn` to avoid shell injection
47
+ - [ ] `fs` operations validate that resolved paths stay within expected directories
48
+ - [ ] Rate limiting on any endpoint that accepts user input
49
+
50
+ ## when to stop and escalate
51
+
52
+ If you find a critical vulnerability (data exposure, auth bypass, RCE), stop
53
+ implementation and report it immediately rather than trying to fix it inline.
@@ -0,0 +1,29 @@
1
+ {
2
+ "version": 1,
3
+ "skills": {
4
+ "find-skills": {
5
+ "source": "vercel-labs/skills",
6
+ "sourceType": "github",
7
+ "skillPath": "skills/find-skills/SKILL.md",
8
+ "computedHash": "b146008599c31057cef1c145774cea5d5afb30e8f43fa802e47a4b461419aaaf"
9
+ },
10
+ "frontend-design": {
11
+ "source": "anthropics/skills",
12
+ "sourceType": "github",
13
+ "skillPath": "skills/frontend-design/SKILL.md",
14
+ "computedHash": "4eabc66183767153e404b39d1b839b1c37f2d82d86f0a0d7e880a579d8d62336"
15
+ },
16
+ "turbopack": {
17
+ "source": "vercel/vercel-plugin",
18
+ "sourceType": "github",
19
+ "skillPath": "skills/turbopack/SKILL.md",
20
+ "computedHash": "cd8c2f189adacb88854c20088ab37dfe077cdc0bc1ded3ec3aa4e40be22bcf3c"
21
+ },
22
+ "vercel-cli": {
23
+ "source": "vercel/vercel-plugin",
24
+ "sourceType": "github",
25
+ "skillPath": "skills/vercel-cli/SKILL.md",
26
+ "computedHash": "730854ddcfabf771468e6ab83d0a3635b006d5e1ecbcc59b5682e1b14dd1f5de"
27
+ }
28
+ }
29
+ }