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.
Files changed (18) hide show
  1. package/ARCHITECTURE.md +3 -1
  2. package/CHANGELOG.md +24 -4
  3. package/README.md +16 -11
  4. package/agent-skill/skanvil/SKILL.md +24 -13
  5. package/agent-skill/skanvil/references/REFERENCE.md +38 -12
  6. package/dist/{chunk-TYO4LLN5.js → chunk-WXEWECJP.js} +658 -133
  7. package/dist/cli.js +22 -3
  8. package/dist/index.d.ts +180 -1
  9. package/dist/index.js +19 -1
  10. package/docs/commands.md +23 -11
  11. package/docs/getting-started.md +46 -0
  12. package/docs/params-and-exports.md +196 -0
  13. package/docs/sync.md +4 -0
  14. package/docs/validation.md +26 -24
  15. package/package.json +1 -1
  16. package/templates/library/README.md +13 -0
  17. package/templates/library/gitignore +1 -0
  18. package/templates/library/package.json +21 -2
package/docs/sync.md CHANGED
@@ -62,6 +62,10 @@ skanvil sync --from @acme/my-skills --target copilot # an installed npm pack
62
62
  - Skills with validation errors are skipped, with a message, unless `--force` is given. README-only problems do not block a skill.
63
63
  - `--category` and `--skill` restrict the selection. Both are repeatable.
64
64
 
65
+ ## Parameters
66
+
67
+ Skills with a `params.json` are installed rendered: `--param name=value` sets values, and defaults fill the rest. The values are remembered per target, so later syncs reuse them. See [Parameters and exports](params-and-exports.md).
68
+
65
69
  ## Copy or link
66
70
 
67
71
  | Mode | How | When to use |
package/docs/validation.md CHANGED
@@ -15,30 +15,32 @@ It also runs automatically after `add` and `edit`.
15
15
 
16
16
  ## Rules
17
17
 
18
- | Rule | Default | Fixable | Checks |
19
- | ---------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
20
- | `skill-file` | error | | Each skill folder contains `SKILL.md`. |
21
- | `frontmatter` | error | | `SKILL.md` starts with valid YAML frontmatter between `---` delimiters, and it is a mapping. |
22
- | `frontmatter-tabs` | error | ✓ | No tab characters in the frontmatter. |
23
- | `folder-name` | error | | The folder name is strict kebab-case (`_` allowed as the internal prefix). |
24
- | `name-required` | error | ✓ | Frontmatter `name` is present. |
25
- | `name-format` | error | | Spec: `name` is 1–64 characters of `a-z`, `0-9` and single hyphens, and does not start or end with a hyphen. |
26
- | `name-matches-folder` | error | ✓ | `name` equals the folder name. |
27
- | `duplicate-name` | error | | No two skills share a frontmatter `name`. |
28
- | `description-required` | error | | Frontmatter `description` is present. |
29
- | `description-length` | error | | Spec: `description` is at most 1024 characters. |
30
- | `compatibility-length` | error | | Spec: `compatibility`, when present, is 1–500 characters. |
31
- | `metadata-format` | warn | | Spec: `metadata` maps string keys to string values. Quote numbers: `version: "1.0"`. |
32
- | `allowed-tools-format` | warn | | Spec: `allowed-tools` is a space-separated string. |
33
- | `tools-field` | warn | ✓ | `tools` is not a spec field. Use `allowed-tools`. |
34
- | `required-sections` | error | | The body contains every heading in `validation.requiredSections`. |
35
- | `placeholders` | error | | The file contains none of `validation.placeholders`. |
36
- | `max-lines` | warn | | `SKILL.md` is at most `validation.maxLines` lines (spec recommendation: 500). |
37
- | `broken-references` | error | | Relative links and `references/`, `scripts/`, `assets/` paths in `SKILL.md` exist inside the skill folder. |
38
- | `template-unchanged` | warn | | The body no longer contains the generic sentences of the built-in skill template. |
39
- | `readme-missing` | error | ✓ | Every indexed skill is listed in the README. |
40
- | `readme-orphan` | error | ✓ | The README does not list skills that don't exist. |
41
- | `readme-section` | error | ✓ | Skills are listed under their own category's section. |
18
+ | Rule | Default | Fixable | Checks |
19
+ | ---------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
20
+ | `skill-file` | error | | Each skill folder contains `SKILL.md`. |
21
+ | `frontmatter` | error | | `SKILL.md` starts with valid YAML frontmatter between `---` delimiters, and it is a mapping. |
22
+ | `frontmatter-tabs` | error | ✓ | No tab characters in the frontmatter. |
23
+ | `folder-name` | error | | The folder name is strict kebab-case (`_` allowed as the internal prefix). |
24
+ | `name-required` | error | ✓ | Frontmatter `name` is present. |
25
+ | `name-format` | error | | Spec: `name` is 1–64 characters of `a-z`, `0-9` and single hyphens, and does not start or end with a hyphen. |
26
+ | `name-matches-folder` | error | ✓ | `name` equals the folder name. |
27
+ | `duplicate-name` | error | | No two skills share a frontmatter `name`. |
28
+ | `description-required` | error | | Frontmatter `description` is present. |
29
+ | `description-length` | error | | Spec: `description` is at most 1024 characters. |
30
+ | `compatibility-length` | error | | Spec: `compatibility`, when present, is 1–500 characters. |
31
+ | `metadata-format` | warn | | Spec: `metadata` maps string keys to string values. Quote numbers: `version: "1.0"`. |
32
+ | `allowed-tools-format` | warn | | Spec: `allowed-tools` is a space-separated string. |
33
+ | `tools-field` | warn | ✓ | `tools` is not a spec field. Use `allowed-tools`. |
34
+ | `required-sections` | error | | The body contains every heading in `validation.requiredSections`. |
35
+ | `placeholders` | error | | The file contains none of `validation.placeholders`. |
36
+ | `max-lines` | warn | | `SKILL.md` is at most `validation.maxLines` lines (spec recommendation: 500). |
37
+ | `broken-references` | error | | Relative links and `references/`, `scripts/`, `assets/` paths in `SKILL.md` exist inside the skill folder. |
38
+ | `template-unchanged` | warn | | The body no longer contains the generic sentences of the built-in skill template. |
39
+ | `params-file` | error | | `params.json`, when present, is valid (camelCase names, a type, a default). See [Parameters](params-and-exports.md). |
40
+ | `params-template` | error | | `{{…}}` placeholders and `{{#if}}` blocks use declared parameters and are balanced. |
41
+ | `readme-missing` | error | ✓ | Every indexed skill is listed in the README. |
42
+ | `readme-orphan` | error | ✓ | The README does not list skills that don't exist. |
43
+ | `readme-section` | error | ✓ | Skills are listed under their own category's section. |
42
44
 
43
45
  **Placeholder matching:**
44
46
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skanvil",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "CLI to generate, extend, validate and sync libraries of Agent Skills.",
5
5
  "author": "Jose Manuel Bargueño López <contact@jmbargueno.com>",
6
6
  "license": "MIT",
package/templates/library/README.md CHANGED
@@ -18,3 +18,16 @@ npx skanvil sync ../app --target claude # install skills into a project
18
18
  ```
19
19
 
20
20
  Categories, validation rules and sync targets are configured in `.skanvilrc.json`.
21
+
22
+ ## Using These Skills From Code
23
+
24
+ `npm run build` (run automatically before publishing) generates typed exports, one function per skill:
25
+
26
+ ```js
27
+ import { skills, getSkill } from "{{packageName}}";
28
+
29
+ for (const skill of skills) console.log(skill.name, skill.description);
30
+ const markdown = getSkill(skills[0].name).render(); // SKILL.md, rendered with default parameters
31
+ ```
32
+
33
+ Skills can declare parameters in a `params.json` next to their `SKILL.md`; see the skanvil docs on parameters and exports.
package/templates/library/gitignore CHANGED
@@ -1,3 +1,4 @@
1
1
  node_modules/
2
+ dist/
2
3
  *.log
3
4
  .DS_Store
package/templates/library/package.json CHANGED
@@ -2,14 +2,33 @@
2
2
  "name": "{{packageName}}",
3
3
  "version": "0.1.0",
4
4
  "description": "{{description}}",
5
+ "main": "./dist/index.cjs",
6
+ "module": "./dist/index.mjs",
7
+ "types": "./dist/index.d.cts",
8
+ "exports": {
9
+ ".": {
10
+ "import": {
11
+ "types": "./dist/index.d.mts",
12
+ "default": "./dist/index.mjs"
13
+ },
14
+ "require": {
15
+ "types": "./dist/index.d.cts",
16
+ "default": "./dist/index.cjs"
17
+ }
18
+ },
19
+ "./package.json": "./package.json"
20
+ },
5
21
  "files": [
22
+ "dist",
6
23
  "skills",
7
24
  "README.md",
8
25
  ".skanvilrc.json"
9
26
  ],
10
27
  "scripts": {
11
- "test": "skanvil validate --strict && skanvil index --check",
28
+ "build": "skanvil build",
12
29
  "prebuild": "skanvil validate",
30
+ "test": "skanvil validate --strict && skanvil index --check",
31
+ "prepublishOnly": "npm run build",
13
32
  "skill:add": "skanvil add",
14
33
  "skill:edit": "skanvil edit",
15
34
  "skill:list": "skanvil list",
@@ -21,6 +40,6 @@
21
40
  "node": ">=20"
22
41
  },
23
42
  "devDependencies": {
24
- "skanvil": "^1.0.0"
43
+ "skanvil": "{{skanvilRange}}"
25
44
  }
26
45
  }