agentic-skill-mill 1.0.5 → 1.0.7

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 (17) hide show
  1. package/README.md +15 -1
  2. package/compiled/claude/agentic-skill-mill/SKILL.md +105 -8
  3. package/compiled/codex/agentic-skill-mill/SKILL.md +105 -8
  4. package/compiled/cursor/rules/agentic-skill-mill.mdc +105 -8
  5. package/compiled/cursor/skills/agentic-skill-mill/SKILL.md +105 -8
  6. package/compiled/opencode/agentic-skill-mill.md +105 -8
  7. package/compiled/windsurf/rules/agentic-skill-mill.md +105 -8
  8. package/compiled/windsurf/skills/agentic-skill-mill/SKILL.md +105 -8
  9. package/install-local.ps1 +385 -0
  10. package/install-local.sh +0 -0
  11. package/install.ps1 +48 -0
  12. package/package.json +8 -2
  13. package/skill/build/manifest.json +1 -0
  14. package/skill/fragments/meta/architecture-overview.md +10 -1
  15. package/skill/fragments/meta/distribution-and-ci.md +77 -0
  16. package/skill/fragments/meta/rename-workflow.md +13 -7
  17. package/skill/skills/agentic-skill-mill/agentic-skill-mill.md +6 -0
package/README.md CHANGED
@@ -12,12 +12,24 @@ bash install-local.sh # local repo setup (auto-detect tools)
12
12
  bash install-local.sh --all # local repo setup for all tools
13
13
  ```
14
14
 
15
+ ```powershell
16
+ npm install
17
+ npm run build
18
+ npm run compile
19
+ powershell -ExecutionPolicy Bypass -File .\install-local.ps1
20
+ powershell -ExecutionPolicy Bypass -File .\install-local.ps1 --all
21
+ ```
22
+
15
23
  ## One-Line Remote Install (No Clone)
16
24
 
17
25
  ```bash
18
26
  bash <(curl -fsSL https://agenticskillmill.com/install.sh) --all
19
27
  ```
20
28
 
29
+ ```powershell
30
+ powershell -ExecutionPolicy Bypass -Command "& ([ScriptBlock]::Create((Invoke-RestMethod 'https://agenticskillmill.com/install.ps1'))) --all"
31
+ ```
32
+
21
33
  This bootstrap script installs the npm utility library globally, then installs skills for the targets you specify.
22
34
 
23
35
  ## Architecture
@@ -81,14 +93,16 @@ compiled/ # Machine-generated, one subdir per IDE target
81
93
  contributions/ # Field observations from real runs
82
94
  site/ # GitHub Pages site (agenticskillmill.com)
83
95
  install-local.sh # One-command local setup: build CLI + install skills
96
+ install-local.ps1 # One-command local setup for Windows PowerShell
84
97
  install.sh # One-command remote bootstrap: install package + skills
98
+ install.ps1 # One-command remote bootstrap for Windows PowerShell
85
99
  ```
86
100
 
87
101
  ## How to Add a Skill
88
102
 
89
103
  1. Create the source file at `skill/skills/<name>/<name>.md` with YAML frontmatter
90
104
  2. Register it in `skill/build/manifest.json`
91
- 3. Add the skill name to the `SKILLS` array in `install-local.sh`
105
+ 3. Add the skill name to the `SKILLS` array in `install-local.sh` and `install-local.ps1`
92
106
  4. Compile and validate: `npm run compile && npm run compile:validate`
93
107
 
94
108
  ## How to Add a Fragment
package/compiled/claude/agentic-skill-mill/SKILL.md CHANGED
@@ -20,9 +20,15 @@ Skills (what to do) CLI Companion (tools to do it with)
20
20
  skill/fragments/*.md src/core/*.ts
21
21
  | |
22
22
  v v
23
- compiled/ (7 IDE formats) dist/ (npm link -> global CLI)
23
+ compiled/ (7 IDE formats) dist/ (npm -> npx or global CLI)
24
24
  | |
25
25
  +---------> Agent <----------+
26
+ ^
27
+ |
28
+ Distribution: npm publish + agenticskillmill.com
29
+ .github/workflows/release.yml (build, test, version, publish)
30
+ .github/workflows/deploy-pages.yml (site/ -> GitHub Pages)
31
+ site/install.sh (curl-friendly bootstrap)
26
32
  ```
27
33
 
28
34
  **Skills** are step-by-step runbooks in markdown with YAML frontmatter. They tell the agent *what* to do. Skills reference the CLI by name so the agent can invoke structured commands.
@@ -48,10 +54,95 @@ Skills (what to do) CLI Companion (tools to do it with)
48
54
  | Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
49
55
  | Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
50
56
  | Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install-local.sh` SKILLS array |
57
+ | Change installer behavior | `install.sh` (repo root) then copy to `site/install.sh` |
58
+ | Update the landing page | `site/index.html`, `site/style.css` |
59
+ | Change CI secrets or workflow | `.github/workflows/release.yml` or `deploy-pages.yml`, repo settings |
51
60
  | Rename the project | See the rename workflow |
52
61
 
53
62
  ---
54
63
 
64
+ ## Distribution and CI
65
+
66
+ ### Distribution model
67
+
68
+ The project is published to npmjs as a public package and hosted at `https://agenticskillmill.com`. There are three ways users consume it:
69
+
70
+ | Method | Command | Who uses it |
71
+ |--------|---------|-------------|
72
+ | Remote install (no clone) | `bash <(curl -fsSL https://agenticskillmill.com/install.sh) --all` | End users who want skills installed into their IDE tools |
73
+ | npx (no install) | `npx --yes agentic-skill-mill@latest <command>` | Users running CLI commands without global install |
74
+ | Local development | `git clone` then `bash install-local.sh --all` | Contributors working on the project itself |
75
+
76
+ ### Two installer scripts
77
+
78
+ **`install-local.sh`** is the full local installer. It runs from a cloned repo and handles:
79
+ - `npm install` + `npm run build` + `npm run compile`
80
+ - `npm link` to make `skillmill` available globally
81
+ - Copies compiled skill outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.)
82
+ - Supports `--skills-only` (skip build, just copy), `--uninstall`, `--compile-only`, and per-tool flags (`--cursor`, `--claude`, etc.)
83
+ - Auto-detects installed tools when no flags are provided
84
+
85
+ **`install.sh`** is the remote bootstrap installer. It is hosted at `https://agenticskillmill.com/install.sh` (source: `site/install.sh`) and bundled in the npm package. It:
86
+ 1. Runs `npm install -g agentic-skill-mill@latest`
87
+ 2. Locates `install-local.sh` inside the globally installed package
88
+ 3. Delegates to `install-local.sh --skills-only` with the user's flags
89
+
90
+ Both scripts respect environment overrides `SKILLMILL_PACKAGE_NAME` and `SKILLMILL_PACKAGE_VERSION`.
91
+
92
+ ### npm package contents
93
+
94
+ The `files` array in `package.json` controls what ships to npm:
95
+
96
+ | Entry | Purpose |
97
+ |-------|---------|
98
+ | `dist` | Compiled TypeScript CLI and library |
99
+ | `compiled` | Pre-compiled skill outputs for all 7 IDE targets |
100
+ | `skill` | Skill sources, fragments, compiler, and manifest |
101
+ | `README.md` | Package documentation |
102
+ | `install.sh` | Bootstrap installer (bundled for remote delegation) |
103
+ | `install-local.sh` | Full local installer (used by bootstrap in --skills-only mode) |
104
+
105
+ The `bin` field maps `skillmill` to `dist/cli/index.js`, so `npx agentic-skill-mill` and global install both expose the `skillmill` command.
106
+
107
+ ### GitHub Actions workflows
108
+
109
+ **Release to npm** (`.github/workflows/release.yml`):
110
+ - Triggers on push to `main` or `workflow_dispatch`
111
+ - Skips runs caused by its own release commits (loop guard via `chore(release):` in commit message)
112
+ - Steps: `npm ci` -> `npm run build` -> `npm run test -- --passWithNoTests` -> `npm run compile` -> `npm run compile:validate` -> version bump -> `git push --follow-tags` -> `npm publish --access public`
113
+ - Version bump finds the next available patch tag to avoid collisions with existing tags
114
+ - Required secrets: `AGENT_TOKEN` (PAT with repo scope for push), `AGENT_NPM_TOKEN` (npm automation token for publish)
115
+
116
+ **Deploy GitHub Pages** (`.github/workflows/deploy-pages.yml`):
117
+ - Triggers on push to `main` when files in `site/` change, or `workflow_dispatch`
118
+ - Uploads `site/` directory as the Pages artifact
119
+ - Deploys to the `github-pages` environment at `agenticskillmill.com`
120
+
121
+ ### The `site/` directory
122
+
123
+ Static site served via GitHub Pages at `https://agenticskillmill.com`:
124
+
125
+ | File | Purpose |
126
+ |------|---------|
127
+ | `site/CNAME` | Custom domain binding |
128
+ | `site/index.html` | Landing page with architecture, CLI commands, and install instructions |
129
+ | `site/style.css` | Site styles |
130
+ | `site/install.sh` | Bootstrap installer served at `https://agenticskillmill.com/install.sh` |
131
+
132
+ When updating the bootstrap installer logic, edit `install.sh` at the repo root and copy it to `site/install.sh` to keep both in sync. The release workflow publishes the repo-root copy to npm; the Pages workflow serves the site copy to the domain.
133
+
134
+ ### Modifying distribution touchpoints
135
+
136
+ | Change | Files to update |
137
+ |--------|----------------|
138
+ | Add a new skill | `install-local.sh` SKILLS array, `skill/build/manifest.json` |
139
+ | Change package name | `package.json` name + bin, `install.sh` default, `site/install.sh` default, `install-local.sh` PROJECT_NAME + CLI_BIN_NAME + MANAGED_MARKER, `site/index.html`, README |
140
+ | Change bootstrap behavior | `install.sh` (repo root), then copy to `site/install.sh` |
141
+ | Add a GitHub Actions secret | Repo settings, document in README |
142
+ | Update domain | `site/CNAME`, README, skill source, architecture fragment |
143
+
144
+ ---
145
+
55
146
  ## Workflow
56
147
 
57
148
  ### Step 1: Understand the Goal
@@ -350,17 +441,23 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
350
441
 
351
442
  4. **Compiler marker** (`skill/build/compile.mjs`) -- update the `MANAGED_BY` constant
352
443
 
353
- 5. **Installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
444
+ 5. **Local installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
445
+
446
+ 6. **Bootstrap installer** (`install.sh`) -- update the default `PACKAGE_NAME`, then copy to `site/install.sh`
447
+
448
+ 7. **Package metadata** (`package.json`) -- update `name`, `bin` key, and `description`
449
+
450
+ 8. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
354
451
 
355
- 6. **Package metadata** (`package.json`) -- update `name` and `bin` key
452
+ 9. **README** -- update title, CLI references, project layout, npx examples, install URLs
356
453
 
357
- 7. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
454
+ 10. **Landing page** (`site/index.html`) -- update title, CLI references, install commands, GitHub link
358
455
 
359
- 8. **README** -- update title, CLI references, project layout example
456
+ 11. **GitHub Actions secrets** -- if the npm package name changed, verify `AGENT_NPM_TOKEN` still works for the new package scope
360
457
 
361
- 9. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
458
+ 12. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
362
459
 
363
- 10. **Regenerate everything:**
460
+ 13. **Regenerate everything:**
364
461
  ```bash
365
462
  rm -rf compiled
366
463
  npm install # regenerates package-lock.json
@@ -373,7 +470,7 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
373
470
  After renaming, run this sweep to confirm no stale references remain:
374
471
 
375
472
  ```bash
376
- grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" .
473
+ grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" --include="*.html" --include="*.yml" .
377
474
  ```
378
475
 
379
476
  The grep should return zero results (excluding node_modules and dist).
package/compiled/codex/agentic-skill-mill/SKILL.md CHANGED
@@ -20,9 +20,15 @@ Skills (what to do) CLI Companion (tools to do it with)
20
20
  skill/fragments/*.md src/core/*.ts
21
21
  | |
22
22
  v v
23
- compiled/ (7 IDE formats) dist/ (npm link -> global CLI)
23
+ compiled/ (7 IDE formats) dist/ (npm -> npx or global CLI)
24
24
  | |
25
25
  +---------> Agent <----------+
26
+ ^
27
+ |
28
+ Distribution: npm publish + agenticskillmill.com
29
+ .github/workflows/release.yml (build, test, version, publish)
30
+ .github/workflows/deploy-pages.yml (site/ -> GitHub Pages)
31
+ site/install.sh (curl-friendly bootstrap)
26
32
  ```
27
33
 
28
34
  **Skills** are step-by-step runbooks in markdown with YAML frontmatter. They tell the agent *what* to do. Skills reference the CLI by name so the agent can invoke structured commands.
@@ -48,10 +54,95 @@ Skills (what to do) CLI Companion (tools to do it with)
48
54
  | Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
49
55
  | Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
50
56
  | Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install-local.sh` SKILLS array |
57
+ | Change installer behavior | `install.sh` (repo root) then copy to `site/install.sh` |
58
+ | Update the landing page | `site/index.html`, `site/style.css` |
59
+ | Change CI secrets or workflow | `.github/workflows/release.yml` or `deploy-pages.yml`, repo settings |
51
60
  | Rename the project | See the rename workflow |
52
61
 
53
62
  ---
54
63
 
64
+ ## Distribution and CI
65
+
66
+ ### Distribution model
67
+
68
+ The project is published to npmjs as a public package and hosted at `https://agenticskillmill.com`. There are three ways users consume it:
69
+
70
+ | Method | Command | Who uses it |
71
+ |--------|---------|-------------|
72
+ | Remote install (no clone) | `bash <(curl -fsSL https://agenticskillmill.com/install.sh) --all` | End users who want skills installed into their IDE tools |
73
+ | npx (no install) | `npx --yes agentic-skill-mill@latest <command>` | Users running CLI commands without global install |
74
+ | Local development | `git clone` then `bash install-local.sh --all` | Contributors working on the project itself |
75
+
76
+ ### Two installer scripts
77
+
78
+ **`install-local.sh`** is the full local installer. It runs from a cloned repo and handles:
79
+ - `npm install` + `npm run build` + `npm run compile`
80
+ - `npm link` to make `skillmill` available globally
81
+ - Copies compiled skill outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.)
82
+ - Supports `--skills-only` (skip build, just copy), `--uninstall`, `--compile-only`, and per-tool flags (`--cursor`, `--claude`, etc.)
83
+ - Auto-detects installed tools when no flags are provided
84
+
85
+ **`install.sh`** is the remote bootstrap installer. It is hosted at `https://agenticskillmill.com/install.sh` (source: `site/install.sh`) and bundled in the npm package. It:
86
+ 1. Runs `npm install -g agentic-skill-mill@latest`
87
+ 2. Locates `install-local.sh` inside the globally installed package
88
+ 3. Delegates to `install-local.sh --skills-only` with the user's flags
89
+
90
+ Both scripts respect environment overrides `SKILLMILL_PACKAGE_NAME` and `SKILLMILL_PACKAGE_VERSION`.
91
+
92
+ ### npm package contents
93
+
94
+ The `files` array in `package.json` controls what ships to npm:
95
+
96
+ | Entry | Purpose |
97
+ |-------|---------|
98
+ | `dist` | Compiled TypeScript CLI and library |
99
+ | `compiled` | Pre-compiled skill outputs for all 7 IDE targets |
100
+ | `skill` | Skill sources, fragments, compiler, and manifest |
101
+ | `README.md` | Package documentation |
102
+ | `install.sh` | Bootstrap installer (bundled for remote delegation) |
103
+ | `install-local.sh` | Full local installer (used by bootstrap in --skills-only mode) |
104
+
105
+ The `bin` field maps `skillmill` to `dist/cli/index.js`, so `npx agentic-skill-mill` and global install both expose the `skillmill` command.
106
+
107
+ ### GitHub Actions workflows
108
+
109
+ **Release to npm** (`.github/workflows/release.yml`):
110
+ - Triggers on push to `main` or `workflow_dispatch`
111
+ - Skips runs caused by its own release commits (loop guard via `chore(release):` in commit message)
112
+ - Steps: `npm ci` -> `npm run build` -> `npm run test -- --passWithNoTests` -> `npm run compile` -> `npm run compile:validate` -> version bump -> `git push --follow-tags` -> `npm publish --access public`
113
+ - Version bump finds the next available patch tag to avoid collisions with existing tags
114
+ - Required secrets: `AGENT_TOKEN` (PAT with repo scope for push), `AGENT_NPM_TOKEN` (npm automation token for publish)
115
+
116
+ **Deploy GitHub Pages** (`.github/workflows/deploy-pages.yml`):
117
+ - Triggers on push to `main` when files in `site/` change, or `workflow_dispatch`
118
+ - Uploads `site/` directory as the Pages artifact
119
+ - Deploys to the `github-pages` environment at `agenticskillmill.com`
120
+
121
+ ### The `site/` directory
122
+
123
+ Static site served via GitHub Pages at `https://agenticskillmill.com`:
124
+
125
+ | File | Purpose |
126
+ |------|---------|
127
+ | `site/CNAME` | Custom domain binding |
128
+ | `site/index.html` | Landing page with architecture, CLI commands, and install instructions |
129
+ | `site/style.css` | Site styles |
130
+ | `site/install.sh` | Bootstrap installer served at `https://agenticskillmill.com/install.sh` |
131
+
132
+ When updating the bootstrap installer logic, edit `install.sh` at the repo root and copy it to `site/install.sh` to keep both in sync. The release workflow publishes the repo-root copy to npm; the Pages workflow serves the site copy to the domain.
133
+
134
+ ### Modifying distribution touchpoints
135
+
136
+ | Change | Files to update |
137
+ |--------|----------------|
138
+ | Add a new skill | `install-local.sh` SKILLS array, `skill/build/manifest.json` |
139
+ | Change package name | `package.json` name + bin, `install.sh` default, `site/install.sh` default, `install-local.sh` PROJECT_NAME + CLI_BIN_NAME + MANAGED_MARKER, `site/index.html`, README |
140
+ | Change bootstrap behavior | `install.sh` (repo root), then copy to `site/install.sh` |
141
+ | Add a GitHub Actions secret | Repo settings, document in README |
142
+ | Update domain | `site/CNAME`, README, skill source, architecture fragment |
143
+
144
+ ---
145
+
55
146
  ## Workflow
56
147
 
57
148
  ### Step 1: Understand the Goal
@@ -350,17 +441,23 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
350
441
 
351
442
  4. **Compiler marker** (`skill/build/compile.mjs`) -- update the `MANAGED_BY` constant
352
443
 
353
- 5. **Installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
444
+ 5. **Local installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
445
+
446
+ 6. **Bootstrap installer** (`install.sh`) -- update the default `PACKAGE_NAME`, then copy to `site/install.sh`
447
+
448
+ 7. **Package metadata** (`package.json`) -- update `name`, `bin` key, and `description`
449
+
450
+ 8. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
354
451
 
355
- 6. **Package metadata** (`package.json`) -- update `name` and `bin` key
452
+ 9. **README** -- update title, CLI references, project layout, npx examples, install URLs
356
453
 
357
- 7. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
454
+ 10. **Landing page** (`site/index.html`) -- update title, CLI references, install commands, GitHub link
358
455
 
359
- 8. **README** -- update title, CLI references, project layout example
456
+ 11. **GitHub Actions secrets** -- if the npm package name changed, verify `AGENT_NPM_TOKEN` still works for the new package scope
360
457
 
361
- 9. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
458
+ 12. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
362
459
 
363
- 10. **Regenerate everything:**
460
+ 13. **Regenerate everything:**
364
461
  ```bash
365
462
  rm -rf compiled
366
463
  npm install # regenerates package-lock.json
@@ -373,7 +470,7 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
373
470
  After renaming, run this sweep to confirm no stale references remain:
374
471
 
375
472
  ```bash
376
- grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" .
473
+ grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" --include="*.html" --include="*.yml" .
377
474
  ```
378
475
 
379
476
  The grep should return zero results (excluding node_modules and dist).
package/compiled/cursor/rules/agentic-skill-mill.mdc CHANGED
@@ -20,9 +20,15 @@ Skills (what to do) CLI Companion (tools to do it with)
20
20
  skill/fragments/*.md src/core/*.ts
21
21
  | |
22
22
  v v
23
- compiled/ (7 IDE formats) dist/ (npm link -> global CLI)
23
+ compiled/ (7 IDE formats) dist/ (npm -> npx or global CLI)
24
24
  | |
25
25
  +---------> Agent <----------+
26
+ ^
27
+ |
28
+ Distribution: npm publish + agenticskillmill.com
29
+ .github/workflows/release.yml (build, test, version, publish)
30
+ .github/workflows/deploy-pages.yml (site/ -> GitHub Pages)
31
+ site/install.sh (curl-friendly bootstrap)
26
32
  ```
27
33
 
28
34
  **Skills** are step-by-step runbooks in markdown with YAML frontmatter. They tell the agent *what* to do. Skills reference the CLI by name so the agent can invoke structured commands.
@@ -48,10 +54,95 @@ Skills (what to do) CLI Companion (tools to do it with)
48
54
  | Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
49
55
  | Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
50
56
  | Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install-local.sh` SKILLS array |
57
+ | Change installer behavior | `install.sh` (repo root) then copy to `site/install.sh` |
58
+ | Update the landing page | `site/index.html`, `site/style.css` |
59
+ | Change CI secrets or workflow | `.github/workflows/release.yml` or `deploy-pages.yml`, repo settings |
51
60
  | Rename the project | See the rename workflow |
52
61
 
53
62
  ---
54
63
 
64
+ ## Distribution and CI
65
+
66
+ ### Distribution model
67
+
68
+ The project is published to npmjs as a public package and hosted at `https://agenticskillmill.com`. There are three ways users consume it:
69
+
70
+ | Method | Command | Who uses it |
71
+ |--------|---------|-------------|
72
+ | Remote install (no clone) | `bash <(curl -fsSL https://agenticskillmill.com/install.sh) --all` | End users who want skills installed into their IDE tools |
73
+ | npx (no install) | `npx --yes agentic-skill-mill@latest <command>` | Users running CLI commands without global install |
74
+ | Local development | `git clone` then `bash install-local.sh --all` | Contributors working on the project itself |
75
+
76
+ ### Two installer scripts
77
+
78
+ **`install-local.sh`** is the full local installer. It runs from a cloned repo and handles:
79
+ - `npm install` + `npm run build` + `npm run compile`
80
+ - `npm link` to make `skillmill` available globally
81
+ - Copies compiled skill outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.)
82
+ - Supports `--skills-only` (skip build, just copy), `--uninstall`, `--compile-only`, and per-tool flags (`--cursor`, `--claude`, etc.)
83
+ - Auto-detects installed tools when no flags are provided
84
+
85
+ **`install.sh`** is the remote bootstrap installer. It is hosted at `https://agenticskillmill.com/install.sh` (source: `site/install.sh`) and bundled in the npm package. It:
86
+ 1. Runs `npm install -g agentic-skill-mill@latest`
87
+ 2. Locates `install-local.sh` inside the globally installed package
88
+ 3. Delegates to `install-local.sh --skills-only` with the user's flags
89
+
90
+ Both scripts respect environment overrides `SKILLMILL_PACKAGE_NAME` and `SKILLMILL_PACKAGE_VERSION`.
91
+
92
+ ### npm package contents
93
+
94
+ The `files` array in `package.json` controls what ships to npm:
95
+
96
+ | Entry | Purpose |
97
+ |-------|---------|
98
+ | `dist` | Compiled TypeScript CLI and library |
99
+ | `compiled` | Pre-compiled skill outputs for all 7 IDE targets |
100
+ | `skill` | Skill sources, fragments, compiler, and manifest |
101
+ | `README.md` | Package documentation |
102
+ | `install.sh` | Bootstrap installer (bundled for remote delegation) |
103
+ | `install-local.sh` | Full local installer (used by bootstrap in --skills-only mode) |
104
+
105
+ The `bin` field maps `skillmill` to `dist/cli/index.js`, so `npx agentic-skill-mill` and global install both expose the `skillmill` command.
106
+
107
+ ### GitHub Actions workflows
108
+
109
+ **Release to npm** (`.github/workflows/release.yml`):
110
+ - Triggers on push to `main` or `workflow_dispatch`
111
+ - Skips runs caused by its own release commits (loop guard via `chore(release):` in commit message)
112
+ - Steps: `npm ci` -> `npm run build` -> `npm run test -- --passWithNoTests` -> `npm run compile` -> `npm run compile:validate` -> version bump -> `git push --follow-tags` -> `npm publish --access public`
113
+ - Version bump finds the next available patch tag to avoid collisions with existing tags
114
+ - Required secrets: `AGENT_TOKEN` (PAT with repo scope for push), `AGENT_NPM_TOKEN` (npm automation token for publish)
115
+
116
+ **Deploy GitHub Pages** (`.github/workflows/deploy-pages.yml`):
117
+ - Triggers on push to `main` when files in `site/` change, or `workflow_dispatch`
118
+ - Uploads `site/` directory as the Pages artifact
119
+ - Deploys to the `github-pages` environment at `agenticskillmill.com`
120
+
121
+ ### The `site/` directory
122
+
123
+ Static site served via GitHub Pages at `https://agenticskillmill.com`:
124
+
125
+ | File | Purpose |
126
+ |------|---------|
127
+ | `site/CNAME` | Custom domain binding |
128
+ | `site/index.html` | Landing page with architecture, CLI commands, and install instructions |
129
+ | `site/style.css` | Site styles |
130
+ | `site/install.sh` | Bootstrap installer served at `https://agenticskillmill.com/install.sh` |
131
+
132
+ When updating the bootstrap installer logic, edit `install.sh` at the repo root and copy it to `site/install.sh` to keep both in sync. The release workflow publishes the repo-root copy to npm; the Pages workflow serves the site copy to the domain.
133
+
134
+ ### Modifying distribution touchpoints
135
+
136
+ | Change | Files to update |
137
+ |--------|----------------|
138
+ | Add a new skill | `install-local.sh` SKILLS array, `skill/build/manifest.json` |
139
+ | Change package name | `package.json` name + bin, `install.sh` default, `site/install.sh` default, `install-local.sh` PROJECT_NAME + CLI_BIN_NAME + MANAGED_MARKER, `site/index.html`, README |
140
+ | Change bootstrap behavior | `install.sh` (repo root), then copy to `site/install.sh` |
141
+ | Add a GitHub Actions secret | Repo settings, document in README |
142
+ | Update domain | `site/CNAME`, README, skill source, architecture fragment |
143
+
144
+ ---
145
+
55
146
  ## Workflow
56
147
 
57
148
  ### Step 1: Understand the Goal
@@ -350,17 +441,23 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
350
441
 
351
442
  4. **Compiler marker** (`skill/build/compile.mjs`) -- update the `MANAGED_BY` constant
352
443
 
353
- 5. **Installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
444
+ 5. **Local installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
445
+
446
+ 6. **Bootstrap installer** (`install.sh`) -- update the default `PACKAGE_NAME`, then copy to `site/install.sh`
447
+
448
+ 7. **Package metadata** (`package.json`) -- update `name`, `bin` key, and `description`
449
+
450
+ 8. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
354
451
 
355
- 6. **Package metadata** (`package.json`) -- update `name` and `bin` key
452
+ 9. **README** -- update title, CLI references, project layout, npx examples, install URLs
356
453
 
357
- 7. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
454
+ 10. **Landing page** (`site/index.html`) -- update title, CLI references, install commands, GitHub link
358
455
 
359
- 8. **README** -- update title, CLI references, project layout example
456
+ 11. **GitHub Actions secrets** -- if the npm package name changed, verify `AGENT_NPM_TOKEN` still works for the new package scope
360
457
 
361
- 9. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
458
+ 12. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
362
459
 
363
- 10. **Regenerate everything:**
460
+ 13. **Regenerate everything:**
364
461
  ```bash
365
462
  rm -rf compiled
366
463
  npm install # regenerates package-lock.json
@@ -373,7 +470,7 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
373
470
  After renaming, run this sweep to confirm no stale references remain:
374
471
 
375
472
  ```bash
376
- grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" .
473
+ grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" --include="*.html" --include="*.yml" .
377
474
  ```
378
475
 
379
476
  The grep should return zero results (excluding node_modules and dist).
package/compiled/cursor/skills/agentic-skill-mill/SKILL.md CHANGED
@@ -20,9 +20,15 @@ Skills (what to do) CLI Companion (tools to do it with)
20
20
  skill/fragments/*.md src/core/*.ts
21
21
  | |
22
22
  v v
23
- compiled/ (7 IDE formats) dist/ (npm link -> global CLI)
23
+ compiled/ (7 IDE formats) dist/ (npm -> npx or global CLI)
24
24
  | |
25
25
  +---------> Agent <----------+
26
+ ^
27
+ |
28
+ Distribution: npm publish + agenticskillmill.com
29
+ .github/workflows/release.yml (build, test, version, publish)
30
+ .github/workflows/deploy-pages.yml (site/ -> GitHub Pages)
31
+ site/install.sh (curl-friendly bootstrap)
26
32
  ```
27
33
 
28
34
  **Skills** are step-by-step runbooks in markdown with YAML frontmatter. They tell the agent *what* to do. Skills reference the CLI by name so the agent can invoke structured commands.
@@ -48,10 +54,95 @@ Skills (what to do) CLI Companion (tools to do it with)
48
54
  | Add a CLI command | `src/core/<name>.ts`, `src/cli/commands/<name>.ts`, `src/cli/index.ts`, `src/index.ts` |
49
55
  | Add a fragment | `skill/fragments/<category>/<name>.md`, `skill/build/manifest.json`, skill source |
50
56
  | Add a skill | `skill/skills/<name>/<name>.md`, `skill/build/manifest.json`, `install-local.sh` SKILLS array |
57
+ | Change installer behavior | `install.sh` (repo root) then copy to `site/install.sh` |
58
+ | Update the landing page | `site/index.html`, `site/style.css` |
59
+ | Change CI secrets or workflow | `.github/workflows/release.yml` or `deploy-pages.yml`, repo settings |
51
60
  | Rename the project | See the rename workflow |
52
61
 
53
62
  ---
54
63
 
64
+ ## Distribution and CI
65
+
66
+ ### Distribution model
67
+
68
+ The project is published to npmjs as a public package and hosted at `https://agenticskillmill.com`. There are three ways users consume it:
69
+
70
+ | Method | Command | Who uses it |
71
+ |--------|---------|-------------|
72
+ | Remote install (no clone) | `bash <(curl -fsSL https://agenticskillmill.com/install.sh) --all` | End users who want skills installed into their IDE tools |
73
+ | npx (no install) | `npx --yes agentic-skill-mill@latest <command>` | Users running CLI commands without global install |
74
+ | Local development | `git clone` then `bash install-local.sh --all` | Contributors working on the project itself |
75
+
76
+ ### Two installer scripts
77
+
78
+ **`install-local.sh`** is the full local installer. It runs from a cloned repo and handles:
79
+ - `npm install` + `npm run build` + `npm run compile`
80
+ - `npm link` to make `skillmill` available globally
81
+ - Copies compiled skill outputs to IDE-specific directories (~/.claude/skills, ~/.cursor/rules, etc.)
82
+ - Supports `--skills-only` (skip build, just copy), `--uninstall`, `--compile-only`, and per-tool flags (`--cursor`, `--claude`, etc.)
83
+ - Auto-detects installed tools when no flags are provided
84
+
85
+ **`install.sh`** is the remote bootstrap installer. It is hosted at `https://agenticskillmill.com/install.sh` (source: `site/install.sh`) and bundled in the npm package. It:
86
+ 1. Runs `npm install -g agentic-skill-mill@latest`
87
+ 2. Locates `install-local.sh` inside the globally installed package
88
+ 3. Delegates to `install-local.sh --skills-only` with the user's flags
89
+
90
+ Both scripts respect environment overrides `SKILLMILL_PACKAGE_NAME` and `SKILLMILL_PACKAGE_VERSION`.
91
+
92
+ ### npm package contents
93
+
94
+ The `files` array in `package.json` controls what ships to npm:
95
+
96
+ | Entry | Purpose |
97
+ |-------|---------|
98
+ | `dist` | Compiled TypeScript CLI and library |
99
+ | `compiled` | Pre-compiled skill outputs for all 7 IDE targets |
100
+ | `skill` | Skill sources, fragments, compiler, and manifest |
101
+ | `README.md` | Package documentation |
102
+ | `install.sh` | Bootstrap installer (bundled for remote delegation) |
103
+ | `install-local.sh` | Full local installer (used by bootstrap in --skills-only mode) |
104
+
105
+ The `bin` field maps `skillmill` to `dist/cli/index.js`, so `npx agentic-skill-mill` and global install both expose the `skillmill` command.
106
+
107
+ ### GitHub Actions workflows
108
+
109
+ **Release to npm** (`.github/workflows/release.yml`):
110
+ - Triggers on push to `main` or `workflow_dispatch`
111
+ - Skips runs caused by its own release commits (loop guard via `chore(release):` in commit message)
112
+ - Steps: `npm ci` -> `npm run build` -> `npm run test -- --passWithNoTests` -> `npm run compile` -> `npm run compile:validate` -> version bump -> `git push --follow-tags` -> `npm publish --access public`
113
+ - Version bump finds the next available patch tag to avoid collisions with existing tags
114
+ - Required secrets: `AGENT_TOKEN` (PAT with repo scope for push), `AGENT_NPM_TOKEN` (npm automation token for publish)
115
+
116
+ **Deploy GitHub Pages** (`.github/workflows/deploy-pages.yml`):
117
+ - Triggers on push to `main` when files in `site/` change, or `workflow_dispatch`
118
+ - Uploads `site/` directory as the Pages artifact
119
+ - Deploys to the `github-pages` environment at `agenticskillmill.com`
120
+
121
+ ### The `site/` directory
122
+
123
+ Static site served via GitHub Pages at `https://agenticskillmill.com`:
124
+
125
+ | File | Purpose |
126
+ |------|---------|
127
+ | `site/CNAME` | Custom domain binding |
128
+ | `site/index.html` | Landing page with architecture, CLI commands, and install instructions |
129
+ | `site/style.css` | Site styles |
130
+ | `site/install.sh` | Bootstrap installer served at `https://agenticskillmill.com/install.sh` |
131
+
132
+ When updating the bootstrap installer logic, edit `install.sh` at the repo root and copy it to `site/install.sh` to keep both in sync. The release workflow publishes the repo-root copy to npm; the Pages workflow serves the site copy to the domain.
133
+
134
+ ### Modifying distribution touchpoints
135
+
136
+ | Change | Files to update |
137
+ |--------|----------------|
138
+ | Add a new skill | `install-local.sh` SKILLS array, `skill/build/manifest.json` |
139
+ | Change package name | `package.json` name + bin, `install.sh` default, `site/install.sh` default, `install-local.sh` PROJECT_NAME + CLI_BIN_NAME + MANAGED_MARKER, `site/index.html`, README |
140
+ | Change bootstrap behavior | `install.sh` (repo root), then copy to `site/install.sh` |
141
+ | Add a GitHub Actions secret | Repo settings, document in README |
142
+ | Update domain | `site/CNAME`, README, skill source, architecture fragment |
143
+
144
+ ---
145
+
55
146
  ## Workflow
56
147
 
57
148
  ### Step 1: Understand the Goal
@@ -350,17 +441,23 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
350
441
 
351
442
  4. **Compiler marker** (`skill/build/compile.mjs`) -- update the `MANAGED_BY` constant
352
443
 
353
- 5. **Installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
444
+ 5. **Local installer** (`install-local.sh`) -- update `PROJECT_NAME`, `CLI_BIN_NAME`, `MANAGED_MARKER`, `SKILLS` array
445
+
446
+ 6. **Bootstrap installer** (`install.sh`) -- update the default `PACKAGE_NAME`, then copy to `site/install.sh`
447
+
448
+ 7. **Package metadata** (`package.json`) -- update `name`, `bin` key, and `description`
449
+
450
+ 8. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
354
451
 
355
- 6. **Package metadata** (`package.json`) -- update `name` and `bin` key
452
+ 9. **README** -- update title, CLI references, project layout, npx examples, install URLs
356
453
 
357
- 7. **CLI metadata** (`src/cli/index.ts`) -- update `.name()` and `.description()` calls
454
+ 10. **Landing page** (`site/index.html`) -- update title, CLI references, install commands, GitHub link
358
455
 
359
- 8. **README** -- update title, CLI references, project layout example
456
+ 11. **GitHub Actions secrets** -- if the npm package name changed, verify `AGENT_NPM_TOKEN` still works for the new package scope
360
457
 
361
- 9. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
458
+ 12. **Any docs** referencing the old name (translation-map, lessons-learned, etc.)
362
459
 
363
- 10. **Regenerate everything:**
460
+ 13. **Regenerate everything:**
364
461
  ```bash
365
462
  rm -rf compiled
366
463
  npm install # regenerates package-lock.json
@@ -373,7 +470,7 @@ When the project, skill, or CLI needs a new name, update all touchpoints in one
373
470
  After renaming, run this sweep to confirm no stale references remain:
374
471
 
375
472
  ```bash
376
- grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" .
473
+ grep -r "<old-name>" --include="*.md" --include="*.json" --include="*.mjs" --include="*.ts" --include="*.sh" --include="*.html" --include="*.yml" .
377
474
  ```
378
475
 
379
476
  The grep should return zero results (excluding node_modules and dist).