skanvil 0.0.0-stage → 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Architecture
+
+skanvil is a TypeScript ESM package. `tsup` bundles `src/` into `dist/` with two entry points: `dist/cli.js` (the `skanvil` binary) and `dist/index.js` (the programmatic API, typed by `dist/index.d.ts`).
+
+## Module map
+
+```text
+src/
+├── cli.ts                 commander program: commands, options, error → exit code
+├── index.ts               public API (re-exports from core/ and commands/)
+├── commands/              thin CLI layer: options → core call → text or JSON output
+│   ├── shared.ts          --cwd handling, diagnostic printing, post-mutation validation
+│   ├── skills.ts          add, edit, list (interactive prompts via @inquirer/prompts)
+│   ├── library.ts         init, validate, index, doctor, templates eject, install-skill, sync
+│   └── wizard.ts          interactive menu-driven assistant on top of the same core calls
+├── core/                  all behaviour; no console output, no process exit
+│   ├── config.ts          .skanvilrc.json zod schema, default preset, resolution and checks
+│   ├── categories.ts      id/alias lookup, longest-prefix inference, name and title building
+│   ├── library.ts         Library: paths, skill listing, SKILL.md and README I/O (keeps EOL)
+│   ├── skill.ts           SkillFile: frontmatter as a YAML Document (round-trip safe)
+│   ├── readme-index.ts    pure functions over the README index (LF text in, LF text out)
+│   ├── validate.ts        rule registry and engine → Diagnostic[]
+│   ├── skills.ts          scaffoldSkill, editSkill (transactional), removeSkill
+│   ├── reindex.ts         rebuildIndex (regenerate) and reconcileIndex (minimal repair)
+│   ├── doctor.ts          diagnosis and automatic fixes
+│   ├── templates.ts       {{variable}} rendering, template lookup, eject
+│   ├── sync.ts            installation into agent folders, manifest, pruning
+│   ├── agent-skill.ts     install/update the bundled `skanvil` agent skill
+│   ├── init.ts            createLibrary
+│   └── naming.ts          kebab-case, title case, sentences
+└── util/                  paths (package root via import.meta.url), eol, fs, output
+
+agent-skill/skanvil/       the `skanvil` agent skill (SKILL.md + references/) shipped to users
+
+templates/
+├── library/               skeleton copied by `init` (gitignore is renamed to .gitignore)
+└── skill/                 default skill: SKILL.md + assets/, references/, scripts/
+
+tests/                     vitest: unit, core end-to-end, and real-CLI suites (tests/setup bundles the CLI)
+scripts/build-schema.mjs   writes schema.json from the zod schema after the build
+docs/                      user guides (docs/assets is not published to npm)
+.github/workflows/         ci.yml (lint, format, typecheck, build, test) and release.yml (release-please PR + npm publish after green CI on main)
+```
+
+## Data flow
+
+```text
+skanvil add --type front --name x --description y
+   │
+   ▼
+cli.ts ──► commands/skills.ts: addCommand(options)
+              │  openLibrary(--cwd) ──► core/library.ts: Library.open
+              │                           └─ core/config.ts: loadConfig → resolveConfig
+              ▼
+           core/skills.ts: scaffoldSkill(library, …)
+              ├─ categories.buildName / buildTitle
+              ├─ templates.resolveSkillTemplate → copyTemplateDir (renderSkillMarkdown)
+              ├─ SkillFile: apply category metadata
+              └─ readme-index.insertEntry → library.writeReadme
+              ▼
+           commands/shared.ts: validateAfter ──► core/validate.ts: validateLibrary
+```
+
+Every command follows the same pattern:
+
+1. The command opens a `Library`, which loads and resolves the config.
+2. It calls a core function.
+3. It prints the result with `Output`, as text or JSON.
+
+Core functions accept a `Library`, or a root path, and never print.
+
+## Design decisions
+
+- **Configuration over constants.** Nothing about a library's conventions is hard-coded: prefixes, README titles, aliases, per-category metadata, required sections and placeholders all live in `.skanvilrc.json`. `DEFAULT_CATEGORIES` is applied when a library has no `categories`.
+- **One prefix-less default category.** A folder belongs to the category with the longest matching prefix, otherwise to the default one. The config loader rejects ambiguous setups: two defaults, a prefix that starts with another prefix, or duplicated aliases or titles.
+- **Plain-markdown README index.** Entries are `- Title` / `\t- Description:` / `` \t- Folder: `skills/x` `` inside `<details><summary><strong>Title</strong></summary>`. `readme-index.ts` works on LF strings only; `Library` detects CRLF on read and restores it on write.
+- **Real YAML, minimal diffs.** `SkillFile` keeps a `yaml` Document. Untouched frontmatter is written back byte for byte, and edited frontmatter is re-serialised without line folding. Template values in the frontmatter are YAML-escaped.
+- **Transactional edits.** `editSkill` computes the new `SKILL.md` and README in memory, writes them, and renames the folder last. On failure it restores both files.
+- **Structured diagnostics.** Each diagnostic carries `rule`, `severity`, `skill`, `message` and `fixable`. This one shape drives text output, `--json`, `doctor --fix` and the sync safety check.
+- **Idempotent sync.** A `.skanvil-sync.json` manifest per target is the only authority on what skanvil may update or delete, so foreign skills are never touched. `--link` uses junctions on Windows, which need no admin rights.
+- **The tool documents itself for agents.** `agent-skill/skanvil` is a normal Agent Skill. A test validates it with skanvil's own default rules, and it must contain no warnings. Installed copies are stamped with `metadata.skanvil-version`; the stamp marks the folder as owned by skanvil, so it can be updated after upgrades.
+- **Templates are data.** Changing how a skill or a library looks never requires touching `src/`.
+- **Supported Node versions drive dependency choices.** Dependencies are pinned to majors that support Node 20: commander 14, @inquirer/prompts 7 and vitest 3.

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project are documented here. Entries are generated by
+[release-please](https://github.com/googleapis/release-please) from
+[Conventional Commits](https://www.conventionalcommits.org/), and versions follow
+[Semantic Versioning](https://semver.org/).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Manuel Bargueño López
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/assets/logo.png" alt="skanvil" width="480">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# skanvil
+
+[![ci](https://github.com/JMBargueno/skanvil/actions/workflows/ci.yml/badge.svg)](https://github.com/JMBargueno/skanvil/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/skanvil.svg)](https://www.npmjs.com/package/skanvil)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Forge, validate and ship libraries of [Agent Skills](https://agentskills.io/specification).**
+
+skanvil is a CLI and Node.js library for teams that maintain a shared set of agent skills, such as a frontend review checklist, a backend migration playbook or an internal release workflow. Each skill lives in its own `SKILL.md`. skanvil handles the repetitive work around them:
+
+- **Scaffolds** new skills from templates, with the right folder prefix, frontmatter and README entry.
+- **Keeps everything in sync** when you rename, re-categorise or delete a skill.
+- **Validates** every skill against the Agent Skills spec and your own conventions, locally or in CI.
+- **Installs** the skills into the folders that coding agents read (`.claude/skills`, `.github/skills`, `.agents/skills`), in any project.
+- **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.
+
+## What is a skills library?
+
+A git repository (and optionally an npm package) with this layout:
+
+```text
+my-skills/
+├── skills/
+│   ├── front-api-review/      # one folder per skill
+│   │   ├── SKILL.md           # YAML frontmatter + instructions
+│   │   ├── references/        # optional long-form guidance
+│   │   ├── scripts/           # optional helpers
+│   │   └── assets/            # optional templates
+│   └── back-migrations/
+├── .claude/skills/skanvil/    # the skanvil agent skill, installed by `init`
+├── README.md                  # human-readable index, maintained by skanvil
+└── .skanvilrc.json            # categories, validation rules, sync targets
+```
+
+Skills are grouped into **categories**, and each category has a folder prefix and a README section. Out of the box these are `front-`, `back-`, prefix-less _transversal_ skills and `_internal` skills. You can define your own categories in `.skanvilrc.json`.
+
+## Install
+
+```bash
+npm install --save-dev skanvil     # or run any command with npx skanvil …
+```
+
+Requires Node.js 20 or later.
+
+## Quick start
+
+**The easy way: run `npx skanvil`** with no arguments in a terminal. A wizard guides you through it:
+
+```text
+$ npx skanvil
+skanvil 1.0.0 · interactive mode · Ctrl+C to quit
+? This folder (projects) is not a skills library. What do you want to do?
+❯ Create a new skills library
+  Install skills from a library into this folder
+  Install or update the skanvil agent skill
+  Exit
+```
+
+What the wizard covers:
+
+- **Outside a library:** creating one, with your own categories if you want.
+- **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.
+- **Learning the flags:** after each action it prints the equivalent command, ready for scripts and CI.
+
+**Author a library with commands:**
+
+```bash
+npx skanvil init my-skills --scope acme
+cd my-skills && npm install
+
+npx skanvil add --type front --name "API review" \
+  --description "Reviews API integration changes for error handling and typing."
+npx skanvil edit front-api-review --rename http-review --type back
+npx skanvil list
+npx skanvil validate --strict
+```
+
+**Use it in a project:**
+
+```bash
+# from a local checkout
+npx skanvil sync ../my-app -C ./my-skills --target claude,copilot
+
+# or from the published package
+cd my-app
+npm install --save-dev @acme/my-skills skanvil
+npx skanvil sync --from @acme/my-skills --target claude
+
+# or for every project on your machine (~/.claude/skills, ~/.copilot/skills, ~/.agents/skills)
+npx skanvil sync -C ./my-skills --global --target claude,copilot
+```
+
+## Commands
+
+| Command                        | What it does                                                                      |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| `skanvil` / `skanvil wizard`   | Interactive assistant (in a terminal; without one, `skanvil` prints the help).    |
+| `skanvil init [dir]`           | Create a new library.                                                             |
+| `skanvil add`                  | Create a skill from a template and index it (interactive if options are missing). |
+| `skanvil edit <skill>`         | Rename, re-categorise, retitle, redescribe or remove a skill. Transactional.      |
+| `skanvil list`                 | Table of skills with category, README presence, validity and description.         |
+| `skanvil validate`             | Check the spec and conventions. Exits 1 on errors.                                |
+| `skanvil index`                | Regenerate the README index (`--check` for CI).                                   |
+| `skanvil doctor`               | Diagnose problems; `--fix` repairs what it can.                                   |
+| `skanvil templates eject`      | Copy the skill template into the library to customise it.                         |
+| `skanvil sync [dest]`          | Install skills into agent folders of a project.                                   |
+| `skanvil install-skill [dest]` | Install or update the `skanvil` agent skill in a project.                         |
+
+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.
+
+## The skanvil agent skill
+
+skanvil includes an Agent Skill, [`agent-skill/skanvil`](agent-skill/skanvil/SKILL.md), that explains the tool to coding agents. It covers:
+
+- how to recognise a skills library;
+- the golden rules: use `add`/`edit` instead of touching folders or the README, and pass every option in non-interactive shells;
+- recipes for common tasks;
+- how to write good skill content;
+- a table from each validation diagnostic to its fix.
+
+`skanvil init` installs it into new libraries, in the configured sync targets (`.claude/skills` by default). To add or refresh it in any repository:
+
+```bash
+npx skanvil install-skill --target claude,copilot,agents   # in the current project
+npx skanvil install-skill --global --target claude          # for every project
+```
+
+Installed copies are stamped with the skanvil version, so running the command again after upgrading updates them. A `skanvil` folder you wrote yourself is never overwritten without `--force`.
+
+## Documentation
+
+| Guide                                      |                                                                        |
+| ------------------------------------------ | ---------------------------------------------------------------------- |
+| [Getting started](docs/getting-started.md) | Build, validate, publish and consume a library, step by step.          |
+| [Commands](docs/commands.md)               | Every command, option and exit code.                                   |
+| [Configuration](docs/configuration.md)     | `.skanvilrc.json` reference: categories, validation, templates, sync.  |
+| [Validation rules](docs/validation.md)     | Every rule, its severity and how to tune it. CI recipes.               |
+| [Templates](docs/templates.md)             | Customising the skill template per library or category.                |
+| [Sync](docs/sync.md)                       | Installing skills into Claude Code, GitHub Copilot and Codex projects. |
+| [API](docs/api.md)                         | Using skanvil from Node.js.                                            |
+| [Architecture](ARCHITECTURE.md)            | How the code is organised.                                             |
+| [Contributing](CONTRIBUTING.md)            | Development setup and conventions.                                     |
+
+## Programmatic API
+
+```ts
+import { Library, scaffoldSkill, validateLibrary, syncSkills } from "skanvil";
+
+const lib = await Library.open("./my-skills");
+await scaffoldSkill(lib, { type: "front", name: "a11y", description: "Audits accessibility." });
+
+const { errors, diagnostics } = await validateLibrary(lib);
+if (errors === 0) await syncSkills(lib, { dest: "../my-app", targets: ["claude"] });
+```
+
+Every export is fully typed and documented; see the [API guide](docs/api.md).
+
+## License
+
+[MIT](LICENSE) © Jose Manuel Bargueño López. See the [changelog](CHANGELOG.md) for release notes.

package/agent-skill/skanvil/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: skanvil
+description: Operate skanvil, the CLI that manages libraries of Agent Skills (a skills/ folder of SKILL.md files, a README index and a .skanvilrc.json). Use it whenever you create, rename, re-categorise, delete, validate or index skills in a repository that has a .skanvilrc.json or depends on skanvil, when fixing skanvil validation errors, or when installing skills into a project's .claude/skills, .github/skills or .agents/skills folders.
+metadata:
+  author: skanvil
+  version: "1.0"
+---
+
+# skanvil
+
+## Objective
+
+Change skills libraries through the `skanvil` CLI, so that skill folders, the `SKILL.md` frontmatter, the README index and the library conventions stay consistent and validation stays green.
+
+## When to Activate This Skill
+
+- The repository has a `.skanvilrc.json`, a `skills/` folder of `SKILL.md` files, or `skanvil` in its `package.json`.
+- The user asks to add, write, rename, move, retitle, redescribe, delete, list, validate or index skills.
+- `skanvil validate`, `npm test` or CI fails with skanvil diagnostics.
+- The user wants a library's skills available to Claude Code, GitHub Copilot or Codex in another project.
+
+## Instructions
+
+### 1. Orient yourself
+
+1. Read `.skanvilrc.json`. It defines the categories (`id`, folder `prefix`, README `title`, `aliases`), the required sections, placeholders and rule severities. A missing file means the default preset: `front-`, `back-`, prefix-less `transversal` (the default) and `_internal`.
+2. Run `npx skanvil list --json` to see every skill with its category, README presence and validity.
+3. Run `npx skanvil validate --json` before changing anything, so you know which problems already existed.
+
+### 2. Golden rules
+
+- **Never rename, move or delete skill folders by hand, and never hand-edit the README index.** Use `skanvil edit`, which keeps the folder, the frontmatter `name`, the `# heading` and the README entry in sync, and rolls back on failure.
+- **Never create skill folders by hand.** Use `skanvil add`, which applies the category prefix, the template, the frontmatter metadata and the README entry.
+- **Always pass every option in non-interactive shells.** `add` needs `--type`, `--name` and `--description`. `edit --remove` needs `--yes`. Otherwise the command prompts, or fails without a TTY.
+- **Never run `skanvil` without arguments or `skanvil wizard`.** They open an interactive menu meant for humans. Use the explicit commands below. If the user prefers menus, suggest they run `npx skanvil` themselves.
+- Add `--json` whenever you need to parse output. Data goes to stdout; warnings and errors go to stderr.
+- Run `npx skanvil validate` after every change and finish with no errors. Exit code `1` means errors, or warnings when `--strict` is used.
+- Prefix every command with `npx` unless `skanvil` is on PATH. Use `-C <path>` to target a library in another folder.
+
+### 3. Common tasks
+
+**Create a skill, then write its content.**
+
+```bash
+npx skanvil add --type <category> --name "<short name>" \
+  --description "<what it does>. Use when <trigger situations>."
+```
+
+Then edit `skills/<prefix><name>/SKILL.md`:
+
+- Fill every required section with concrete, actionable content.
+- Replace all the generic template sentences. Until you do, `validate` reports a `template-unchanged` warning, and `validate --strict` (the library's `npm test`) fails.
+- Move long material into `references/`, and link only to files that exist (`broken-references`).
+
+Use `--no-scripts`, `--no-assets` or `--no-references` when those folders would stay empty. Use `--template <name>` for a custom template in `.skanvil/templates/`.
+
+**Rename or move a skill.**
+
+```bash
+npx skanvil edit <skill> --rename <new-name>          # prefix is re-applied automatically
+npx skanvil edit <skill> --type <other-category>      # new prefix, README section, metadata
+npx skanvil edit <skill> --title "<Title>" --description "<text>"
+```
+
+`--rename` takes the base name: `edit front-a --rename b` gives `front-b`.
+
+**Delete a skill.** Confirm with the user first; this is permanent.
+
+```bash
+npx skanvil edit <skill> --remove --yes
+```
+
+**Fix validation errors.**
+
+1. Run `npx skanvil doctor --fix`. It repairs README entries, `name` mismatches, tabs in the frontmatter and converts `tools` to `allowed-tools`.
+2. Fix what remains by editing `SKILL.md`. Use the diagnostic table below.
+3. Run `npx skanvil validate` again.
+
+**Rebuild the README index** after changing category titles in `.skanvilrc.json`:
+
+```bash
+npx skanvil index          # rewrites the index sections
+npx skanvil index --check  # verify only (CI)
+```
+
+**Install the skills into a project.**
+
+```bash
+npx skanvil sync <project-dir> -C <library-dir> --target claude,copilot --dry-run   # preview
+npx skanvil sync <project-dir> -C <library-dir> --target claude,copilot
+npx skanvil sync --from @scope/package --target agents                             # installed package
+```
+
+Targets:
+
+- `claude` installs into `.claude/skills`;
+- `copilot` installs into `.github/skills`;
+- `agents` and `codex` install into `.agents/skills`.
+- A custom path must be a folder inside the project.
+- `--global` (with no project dir) installs into the user's `~/.claude/skills`, `~/.copilot/skills` or `~/.agents/skills` instead. Only use it when the user asks for skills available in every project.
+
+How sync behaves:
+
+- It never overwrites folders it did not install.
+- It prunes skills that were removed from the library.
+- It skips skills with validation errors unless `--force` is given.
+- It never publishes `_internal` skills.
+
+**Add or change categories.** Edit `categories` in `.skanvilrc.json`:
+
+- exactly one category has `"default": true` and no prefix;
+- every other category has a prefix that is `_` or kebab-case ending in `-`;
+- no prefix may start with another prefix.
+
+Then move existing skills with `edit --type`, and run `skanvil index`.
+
+### 4. Write good skill content
+
+- **`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.
+- **`name`** equals the folder name: lowercase letters, digits and single hyphens, at most 64 characters.
+- **Body:** keep `SKILL.md` under 500 lines. Write instructions as numbered, verifiable steps, and put examples, edge cases and long checklists in `references/` (one level deep).
+- **Placeholders:** never leave filler text. Any entry of `validation.placeholders` (to-do markers, dummy Latin text, "to be decided" notes) fails validation.
+- **`metadata`:** string values only, so quote numbers, as in `version: "1.0"`.
+- **`allowed-tools`:** a space-separated string, not a list.
+
+### 5. Diagnostic → fix
+
+| Rule                                                | Fix                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `readme-missing`, `readme-orphan`, `readme-section` | `npx skanvil doctor --fix`                                                     |
+| `name-matches-folder`, `name-required`              | `doctor --fix`, or `edit --rename` if the folder name is wrong                 |
+| `frontmatter-tabs`, `tools-field`                   | `doctor --fix`                                                                 |
+| `frontmatter`                                       | Repair the YAML between the `---` lines (quote values containing `: ` or `#`). |
+| `required-sections`                                 | Add the missing `## Section` listed in `validation.requiredSections`.          |
+| `placeholders`                                      | Replace the placeholder text with real content.                                |
+| `description-length`, `max-lines`                   | Shorten; move detail to `references/`.                                         |
+| `metadata-format`                                   | Quote non-string values.                                                       |
+| `duplicate-name`                                    | Two folders share a `name`: rename one with `edit --rename`.                   |
+| `broken-references`                                 | Create the referenced file, or fix the link (paths are relative to the skill). |
+| `template-unchanged`                                | Rewrite the generic scaffold sentences with skill-specific instructions.       |
+
+See [references/REFERENCE.md](references/REFERENCE.md) for every command option, the config schema and JSON output shapes.
+
+## Output Format
+
+Report to the user:
+
+- the skanvil commands you ran;
+- the skills created, changed or removed, with their folder names;
+- the final `skanvil validate` result (errors and warnings), and anything left for them to decide.
+
+## Quality Criteria
+
+- Every structural change went through `skanvil add` or `skanvil edit`. There are no hand-made folder renames or README index edits.
+- `npx skanvil validate` reports no errors, and `npx skanvil index --check` passes.
+- New or edited skills have specific descriptions with triggers, and no template filler or placeholders.
+- Deletions and syncs into other projects were confirmed with the user.

package/agent-skill/skanvil/references/REFERENCE.md

@@ -0,0 +1,96 @@
+# skanvil reference
+
+## Commands
+
+Every command accepts `-C, --cwd <path>` (library root) and `--json`. Exit code `0` means success; `1` means an error or failed check.
+
+| Command                | Options                                                                                                                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `init [dir]`           | `--name`, `--scope`, `--description`, `--profile front,back,transversal`, `--no-git`, `--eject-templates`, `--no-agent-skill`, `--target <preset\|path>`                                                     |
+| `add`                  | `--type <category>`, `--name`, `--title`, `--description`, `--template <name>`, `--no-assets`, `--no-references`, `--no-scripts`, `--skip-validate`                                                          |
+| `edit <skill>`         | `--rename`, `--type`, `--title`, `--description`, `--remove`, `--yes`, `--skip-validate`                                                                                                                     |
+| `list`                 | `--category <id>`                                                                                                                                                                                            |
+| `validate`             | `--strict`, `--skill <name>`                                                                                                                                                                                 |
+| `index`                | `--check`                                                                                                                                                                                                    |
+| `doctor`               | `--fix`                                                                                                                                                                                                      |
+| `templates eject`      | `--category <id>`, `--force`                                                                                                                                                                                 |
+| `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) |
+| `install-skill [dest]` | `--target <preset\|path>`, `--force`, `--global` (presets only, no dest)                                                                                                                                     |
+
+## `.skanvilrc.json`
+
+```jsonc
+{
+  "$schema": "./node_modules/skanvil/schema.json",
+  "name": "my-skills",
+  "skillsDir": "skills", // default
+  "readme": "README.md", // default
+  "categories": [
+    {
+      "id": "front", // used by --type
+      "prefix": "front-", // "" (default category only), "_" or kebab-case ending in "-"
+      "title": "Front", // README section title
+      "aliases": ["frontend", "f"],
+      "default": false, // exactly one category is the default (empty prefix)
+      "indexed": true, // listed in the README
+      "validated": true, // validated against the spec and syncable
+      "metadata": { "domain": "frontend" },
+      "compatibility": "Designed for frontend repositories."
+    }
+  ],
+  "validation": {
+    "requiredSections": [
+      "Objective",
+      "When to Activate This Skill",
+      "Instructions",
+      "Output Format",
+      "Quality Criteria"
+    ],
+    "placeholders": ["TODO", "describe...", "lorem ipsum", "tbd", "to be defined"],
+    "maxLines": 500,
+    "rules": { "max-lines": "warn" } // error | warn | off per rule id
+  },
+  "templates": { "dir": ".skanvil/templates" },
+  "sync": { "targets": ["claude"], "mode": "copy" }
+}
+```
+
+## Validation rules
+
+Default severity is `error` unless noted. Rules marked with `*` are fixable by `doctor --fix`.
+
+- **Files and YAML:** `skill-file`, `frontmatter`, `frontmatter-tabs`*.
+- **Names:**
+  - `folder-name`;
+  - `name-required`*;
+  - `name-format`: 1–64 characters of `a-z0-9-`, with no leading, trailing or double hyphens;
+  - `name-matches-folder`*;
+  - `duplicate-name`.
+- **Spec fields:**
+  - `description-required`;
+  - `description-length` (≤ 1024);
+  - `compatibility-length` (1–500);
+  - `metadata-format` (warn);
+  - `allowed-tools-format` (warn);
+  - `tools-field`* (warn).
+- **Content:** `required-sections`, `placeholders`, `max-lines` (warn), `broken-references`, `template-unchanged` (warn).
+- **README:** `readme-missing`_, `readme-orphan`_, `readme-section`*.
+
+## JSON output shapes
+
+- `list --json` prints `[{ name, type, indexed, valid, description }]`. `indexed` and `valid` are `null` for categories that are not indexed or not validated.
+- `validate --json` prints `{ ok, diagnostics: [{ rule, severity, skill?, message, fixable? }], count, errors, warnings }`.
+- `doctor --json` prints the same as validate, plus `fixes: string[]`.
+- `index --json` prints `{ updated }`, or `{ upToDate }` with `--check`.
+- `sync --json` prints `{ dryRun, mode, results: [{ target, path, added, updated, unchanged, removed, skipped: [{ skill, reason }], warnings }] }`.
+- `add --json` prints `{ skillName, title, type, target, template }`.
+- `edit --json` prints `{ skillName, previousName }`, or `{ removed }`.
+
+## Template variables
+
+The following variables are available in custom templates. In the `SKILL.md` frontmatter they are YAML-escaped automatically.
+
+- `{{name}}`, `{{title}}`, `{{description}}`, `{{descriptionLower}}`;
+- `{{category}}`, `{{domain}}`, `{{compatibility}}`;
+- `{{resources}}`;
+- `{{metadata.<key>}}`.