skanvil 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ARCHITECTURE.md +3 -1
- package/CHANGELOG.md +24 -4
- package/README.md +16 -11
- package/agent-skill/skanvil/SKILL.md +24 -13
- package/agent-skill/skanvil/references/REFERENCE.md +38 -12
- package/dist/{chunk-TYO4LLN5.js → chunk-WXEWECJP.js} +658 -133
- package/dist/cli.js +22 -3
- package/dist/index.d.ts +180 -1
- package/dist/index.js +19 -1
- package/docs/commands.md +23 -11
- package/docs/getting-started.md +46 -0
- package/docs/params-and-exports.md +196 -0
- package/docs/sync.md +4 -0
- package/docs/validation.md +26 -24
- package/package.json +1 -1
- package/templates/library/README.md +13 -0
- package/templates/library/gitignore +1 -0
- package/templates/library/package.json +21 -2
package/ARCHITECTURE.md
CHANGED
|
@@ -24,7 +24,9 @@ src/
|
|
|
24
24
|
│ ├── reindex.ts rebuildIndex (regenerate) and reconcileIndex (minimal repair)
|
|
25
25
|
│ ├── doctor.ts diagnosis and automatic fixes
|
|
26
26
|
│ ├── templates.ts {{variable}} rendering, template lookup, eject
|
|
27
|
-
│ ├── sync.ts installation into agent folders, manifest, pruning
|
|
27
|
+
│ ├── sync.ts installation into agent folders, manifest, pruning, --param rendering
|
|
28
|
+
│ ├── params.ts params.json schema, template renderer ({{name}}, {{#if}}), value checks
|
|
29
|
+
│ ├── build.ts skanvil build: typed ESM/CJS exports with the renderer embedded
|
|
28
30
|
│ ├── agent-skill.ts install/update the bundled `skanvil` agent skill
|
|
29
31
|
│ ├── init.ts createLibrary
|
|
30
32
|
│ └── naming.ts kebab-case, title case, sentences
|
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,26 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
## [1.1.0](https://github.com/JMBargueno/skanvil/compare/v1.0.0...v1.1.0) (2026-11-11)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* parametrized skills and typed package exports ([7f9ff65](https://github.com/JMBargueno/skanvil/commit/7f9ff659140591b5ccc56f867f831853d2573d44))
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Documentation
|
|
12
|
+
|
|
13
|
+
* add an AI agent setup prompt to getting started ([ee3adae](https://github.com/JMBargueno/skanvil/commit/ee3adae981baab3b5244b555024ac9122d47b56b))
|
|
14
|
+
|
|
15
|
+
## 1.0.0 (2026-11-10)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
### Features
|
|
19
|
+
|
|
20
|
+
* add interactive wizard ([e3643f8](https://github.com/JMBargueno/skanvil/commit/e3643f8d5034ada4d0a0bf07e9b64270ca3a16fb))
|
|
21
|
+
* initial release of skanvil ([a3fa166](https://github.com/JMBargueno/skanvil/commit/a3fa166f1af05b3e60c9ca17a9adbc8826c0042d))
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Documentation
|
|
25
|
+
|
|
26
|
+
* use canonical JMBargueno casing in repository URLs ([139bd66](https://github.com/JMBargueno/skanvil/commit/139bd66ab267d8ada6557ea91d84e11df88a4803))
|
package/README.md
CHANGED
|
@@ -16,6 +16,7 @@ skanvil is a CLI and Node.js library for teams that maintain a shared set of age
|
|
|
16
16
|
- **Keeps everything in sync** when you rename, re-categorise or delete a skill.
|
|
17
17
|
- **Validates** every skill against the Agent Skills spec and your own conventions, locally or in CI.
|
|
18
18
|
- **Installs** the skills into the folders that coding agents read (`.claude/skills`, `.github/skills`, `.agents/skills`), in any project.
|
|
19
|
+
- **Adapts and exports skills.** Optional parameters (`{{ticketTracker}}`, `{{#if …}}`) make one skill fit every team, and `skanvil build` turns the library into a typed npm package: `import { codeReview } from "@acme/skills"`.
|
|
19
20
|
- **Teaches agents to use it.** skanvil ships its own `skanvil` agent skill, so Claude Code, Copilot or Codex working in your library run the CLI correctly instead of editing folders and the README by hand.
|
|
20
21
|
|
|
21
22
|
## What is a skills library?
|
|
@@ -66,6 +67,8 @@ What the wizard covers:
|
|
|
66
67
|
- **Inside a library:** adding, editing, moving and deleting skills, checking and repairing the library, and installing the skills into a project or for your user. Installs show a preview before anything is written.
|
|
67
68
|
- **Learning the flags:** after each action it prints the equivalent command, ready for scripts and CI.
|
|
68
69
|
|
|
70
|
+
**Or let your AI agent do it:** paste the [setup prompt](docs/getting-started.md#0-let-your-ai-agent-learn-skanvil-optional) into Claude Code, Copilot or Codex. It installs the skanvil agent skill and the agent learns the tool, so you can then ask for skills in plain language.
|
|
71
|
+
|
|
69
72
|
**Author a library with commands:**
|
|
70
73
|
|
|
71
74
|
```bash
|
|
@@ -109,6 +112,7 @@ npx skanvil sync -C ./my-skills --global --target claude,copilot
|
|
|
109
112
|
| `skanvil templates eject` | Copy the skill template into the library to customise it. |
|
|
110
113
|
| `skanvil sync [dest]` | Install skills into agent folders of a project. |
|
|
111
114
|
| `skanvil install-skill [dest]` | Install or update the `skanvil` agent skill in a project. |
|
|
115
|
+
| `skanvil build` | Generate the library's typed npm exports, one function per skill. |
|
|
112
116
|
|
|
113
117
|
Every command accepts `--json`, and every command that works on a library accepts `-C, --cwd <path>`. The [command reference](docs/commands.md) lists every option.
|
|
114
118
|
|
|
@@ -133,17 +137,18 @@ Installed copies are stamped with the skanvil version, so running the command ag
|
|
|
133
137
|
|
|
134
138
|
## Documentation
|
|
135
139
|
|
|
136
|
-
| Guide
|
|
137
|
-
|
|
|
138
|
-
| [Getting started](docs/getting-started.md)
|
|
139
|
-
| [Commands](docs/commands.md)
|
|
140
|
-
| [Configuration](docs/configuration.md)
|
|
141
|
-
| [Validation rules](docs/validation.md)
|
|
142
|
-
| [Templates](docs/templates.md)
|
|
143
|
-
| [
|
|
144
|
-
| [
|
|
145
|
-
| [
|
|
146
|
-
| [
|
|
140
|
+
| Guide | |
|
|
141
|
+
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
142
|
+
| [Getting started](docs/getting-started.md) | Build, validate, publish and consume a library, step by step. |
|
|
143
|
+
| [Commands](docs/commands.md) | Every command, option and exit code. |
|
|
144
|
+
| [Configuration](docs/configuration.md) | `.skanvilrc.json` reference: categories, validation, templates, sync. |
|
|
145
|
+
| [Validation rules](docs/validation.md) | Every rule, its severity and how to tune it. CI recipes. |
|
|
146
|
+
| [Templates](docs/templates.md) | Customising the skill template per library or category. |
|
|
147
|
+
| [Parameters and exports](docs/params-and-exports.md) | Parametrized skills, `sync --param`, and `import { codeReview } from "@acme/skills"`. |
|
|
148
|
+
| [Sync](docs/sync.md) | Installing skills into Claude Code, GitHub Copilot and Codex projects. |
|
|
149
|
+
| [API](docs/api.md) | Using skanvil from Node.js. |
|
|
150
|
+
| [Architecture](ARCHITECTURE.md) | How the code is organised. |
|
|
151
|
+
| [Contributing](CONTRIBUTING.md) | Development setup and conventions. |
|
|
147
152
|
|
|
148
153
|
## Programmatic API
|
|
149
154
|
|
|
@@ -114,6 +114,15 @@ How sync behaves:
|
|
|
114
114
|
|
|
115
115
|
Then move existing skills with `edit --type`, and run `skanvil index`.
|
|
116
116
|
|
|
117
|
+
**Parametrize a skill.** Do this when variants of a skill differ only in details, such as the tracker, package manager or URLs.
|
|
118
|
+
|
|
119
|
+
1. Add a `params.json` next to its `SKILL.md`, for example `{"ticketTracker": {"type": "enum", "values": ["github", "jira"], "default": "github"}}`. Types are `enum`, `string` and `boolean`, and every parameter needs a `default`.
|
|
120
|
+
2. In `SKILL.md`, use `{{ticketTracker}}`, `{{#if ticketTracker == "jira"}}…{{else}}…{{/if}}` and `{{#if strict}}…{{/if}}`.
|
|
121
|
+
3. Run `npx skanvil validate`: it checks the skill rendered with the defaults, plus the `params-file` and `params-template` rules.
|
|
122
|
+
4. Install it with values: `npx skanvil sync <project> --param ticketTracker=jira`.
|
|
123
|
+
|
|
124
|
+
**Export skills as code.** `npx skanvil build` generates `dist/`, with one typed function per skill (`front-code-review` becomes `codeReview(params)`), plus `skills` and `getSkill(name)`. Generated libraries run it in `npm run build` and before publishing.
|
|
125
|
+
|
|
117
126
|
### 4. Write good skill content
|
|
118
127
|
|
|
119
128
|
- **`description`** says _what_ the skill does and _when_ to use it, with the trigger keywords an agent would see. It must be at most 1024 characters.
|
|
@@ -125,19 +134,21 @@ Then move existing skills with `edit --type`, and run `skanvil index`.
|
|
|
125
134
|
|
|
126
135
|
### 5. Diagnostic → fix
|
|
127
136
|
|
|
128
|
-
| Rule | Fix
|
|
129
|
-
| --------------------------------------------------- |
|
|
130
|
-
| `readme-missing`, `readme-orphan`, `readme-section` | `npx skanvil doctor --fix`
|
|
131
|
-
| `name-matches-folder`, `name-required` | `doctor --fix`, or `edit --rename` if the folder name is wrong
|
|
132
|
-
| `frontmatter-tabs`, `tools-field` | `doctor --fix`
|
|
133
|
-
| `frontmatter` | Repair the YAML between the `---` lines (quote values containing `: ` or `#`).
|
|
134
|
-
| `required-sections` | Add the missing `## Section` listed in `validation.requiredSections`.
|
|
135
|
-
| `placeholders` | Replace the placeholder text with real content.
|
|
136
|
-
| `description-length`, `max-lines` | Shorten; move detail to `references/`.
|
|
137
|
-
| `metadata-format` | Quote non-string values.
|
|
138
|
-
| `duplicate-name` | Two folders share a `name`: rename one with `edit --rename`.
|
|
139
|
-
| `broken-references` | Create the referenced file, or fix the link (paths are relative to the skill).
|
|
140
|
-
| `template-unchanged` | Rewrite the generic scaffold sentences with skill-specific instructions.
|
|
137
|
+
| Rule | Fix |
|
|
138
|
+
| --------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
139
|
+
| `readme-missing`, `readme-orphan`, `readme-section` | `npx skanvil doctor --fix` |
|
|
140
|
+
| `name-matches-folder`, `name-required` | `doctor --fix`, or `edit --rename` if the folder name is wrong |
|
|
141
|
+
| `frontmatter-tabs`, `tools-field` | `doctor --fix` |
|
|
142
|
+
| `frontmatter` | Repair the YAML between the `---` lines (quote values containing `: ` or `#`). |
|
|
143
|
+
| `required-sections` | Add the missing `## Section` listed in `validation.requiredSections`. |
|
|
144
|
+
| `placeholders` | Replace the placeholder text with real content. |
|
|
145
|
+
| `description-length`, `max-lines` | Shorten; move detail to `references/`. |
|
|
146
|
+
| `metadata-format` | Quote non-string values. |
|
|
147
|
+
| `duplicate-name` | Two folders share a `name`: rename one with `edit --rename`. |
|
|
148
|
+
| `broken-references` | Create the referenced file, or fix the link (paths are relative to the skill). |
|
|
149
|
+
| `template-unchanged` | Rewrite the generic scaffold sentences with skill-specific instructions. |
|
|
150
|
+
| `params-file` | Fix `params.json`: camelCase names, `type`, a `default` (inside `values` for enums). |
|
|
151
|
+
| `params-template` | Declare every `{{name}}` used, and balance `{{#if}}` / `{{/if}}`. |
|
|
141
152
|
|
|
142
153
|
See [references/REFERENCE.md](references/REFERENCE.md) for every command option, the config schema and JSON output shapes.
|
|
143
154
|
|
|
@@ -4,18 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
Every command accepts `-C, --cwd <path>` (library root) and `--json`. Exit code `0` means success; `1` means an error or failed check.
|
|
6
6
|
|
|
7
|
-
| Command | Options
|
|
8
|
-
| ---------------------- |
|
|
9
|
-
| `init [dir]` | `--name`, `--scope`, `--description`, `--profile front,back,transversal`, `--no-git`, `--eject-templates`, `--no-agent-skill`, `--target <preset\|path>`
|
|
10
|
-
| `add` | `--type <category>`, `--name`, `--title`, `--description`, `--template <name>`, `--no-assets`, `--no-references`, `--no-scripts`, `--skip-validate`
|
|
11
|
-
| `edit <skill>` | `--rename`, `--type`, `--title`, `--description`, `--remove`, `--yes`, `--skip-validate`
|
|
12
|
-
| `list` | `--category <id>`
|
|
13
|
-
| `validate` | `--strict`, `--skill <name>`
|
|
14
|
-
| `index` | `--check`
|
|
15
|
-
| `doctor` | `--fix`
|
|
16
|
-
| `templates eject` | `--category <id>`, `--force`
|
|
17
|
-
| `sync [dest]` | `--target <preset\|path>` (repeatable/comma-separated, must stay inside dest), `--from <pkg\|path>`, `--link`, `--copy`, `--category`, `--skill`, `--force`, `--dry-run`, `--global` (presets only, no dest) |
|
|
18
|
-
| `
|
|
7
|
+
| Command | Options |
|
|
8
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| `init [dir]` | `--name`, `--scope`, `--description`, `--profile front,back,transversal`, `--no-git`, `--eject-templates`, `--no-agent-skill`, `--target <preset\|path>` |
|
|
10
|
+
| `add` | `--type <category>`, `--name`, `--title`, `--description`, `--template <name>`, `--no-assets`, `--no-references`, `--no-scripts`, `--skip-validate` |
|
|
11
|
+
| `edit <skill>` | `--rename`, `--type`, `--title`, `--description`, `--remove`, `--yes`, `--skip-validate` |
|
|
12
|
+
| `list` | `--category <id>` |
|
|
13
|
+
| `validate` | `--strict`, `--skill <name>` |
|
|
14
|
+
| `index` | `--check` |
|
|
15
|
+
| `doctor` | `--fix` |
|
|
16
|
+
| `templates eject` | `--category <id>`, `--force` |
|
|
17
|
+
| `sync [dest]` | `--target <preset\|path>` (repeatable/comma-separated, must stay inside dest), `--from <pkg\|path>`, `--link`, `--copy`, `--category`, `--skill`, `--force`, `--dry-run`, `--global` (presets only, no dest), `--param name=value` (repeatable, remembered per target) |
|
|
18
|
+
| `build` | `--out <dir>`, `--force` |
|
|
19
|
+
| `install-skill [dest]` | `--target <preset\|path>`, `--force`, `--global` (presets only, no dest) |
|
|
19
20
|
|
|
20
21
|
## `.skanvilrc.json`
|
|
21
22
|
|
|
@@ -86,6 +87,31 @@ Default severity is `error` unless noted. Rules marked with `*` are fixable by `
|
|
|
86
87
|
- `add --json` prints `{ skillName, title, type, target, template }`.
|
|
87
88
|
- `edit --json` prints `{ skillName, previousName }`, or `{ removed }`.
|
|
88
89
|
|
|
90
|
+
## Parameters (`params.json`)
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"ticketTracker": { "type": "enum", "values": ["github", "jira"], "default": "github", "description": "…" },
|
|
95
|
+
"packageManager": { "type": "string", "default": "npm" },
|
|
96
|
+
"strict": { "type": "boolean", "default": false }
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The syntax inside `SKILL.md`:
|
|
101
|
+
|
|
102
|
+
- `{{name}}` inserts the value;
|
|
103
|
+
- `{{#if name}}`, `{{#if !name}}`, `{{#if name == "v"}}` and `{{#if name != "v"}}` start a block;
|
|
104
|
+
- `{{else}}` and `{{/if}}` continue and close it.
|
|
105
|
+
|
|
106
|
+
A tag alone on its line removes the line.
|
|
107
|
+
|
|
108
|
+
What the build generates (`skanvil build`):
|
|
109
|
+
|
|
110
|
+
- `dist/index.mjs` and `index.cjs`, plus their `.d.mts` and `.d.cts` declarations;
|
|
111
|
+
- one export per skill, `<camelName>(params?) => string`;
|
|
112
|
+
- `skills`, an array with `{ name, category, title, description, params, render(params), files(params) }` for each skill;
|
|
113
|
+
- `getSkill(name)`.
|
|
114
|
+
|
|
89
115
|
## Template variables
|
|
90
116
|
|
|
91
117
|
The following variables are available in custom templates. In the `SKILL.md` frontmatter they are YAML-escaped automatically.
|