agentic-skill-mill 1.0.5 → 1.0.6

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