diff --git a/AGENTS.md b/AGENTS.md index 55b89b5..f7abf04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Skern is a minimal, agent-first CLI tool for managing Agent Skills across agentic development platforms (Claude Code, Codex CLI, OpenCode, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Continue, and more). It follows the Agent Skills open standard (agentskills.io) and uses `SKILL.md` files with YAML frontmatter as the canonical format. -The project is written in **Go 1.25+** and the current release is **v0.2.0**. +The project is written in **Go 1.25+** and the current release is **v0.3.0**. ## Repository Layout @@ -267,7 +267,10 @@ The full list is generated from `internal/platform/spec.go` — append a row the ## Current Status -Milestones M0–M6 are complete (v0.2.0). M6 shipped dynamic skill loading per #52 — batch install/uninstall, capacity reporting in install/uninstall output, `--enforce-budget` opt-in, `--with-platforms` flag on `skill list`, removal of `--platform all`. The v0.1.x → v0.2.0 transition introduced a **breaking change** to the JSON shape of install/uninstall results (`skills[]` + top-level `platform`/`capacity` instead of `platforms[]`). +Milestones M0–M7 are complete (v0.3.0). + +- **M6** (v0.2.0) — dynamic skill loading per #52: batch install/uninstall, capacity reporting in install/uninstall output, `--enforce-budget` opt-in, `--with-platforms` flag on `skill list`, removal of `--platform all`. The v0.1.x → v0.2.0 transition introduced a breaking change to the JSON shape of install/uninstall results (`skills[]` + top-level `platform`/`capacity` instead of `platforms[]`). +- **M7** (v0.3.0) — declarative platform registry: per-platform Go files collapsed into a single `Spec` table (`internal/platform/spec.go`) plus a generic `Adapter`. Five new adapters (`cursor`, `gemini-cli`, `github-copilot`, `windsurf`, `continue`) shipped alongside the rewrite. Also in v0.3.0: `skern init --instructions` writes the skern usage snippet into agent instruction files, `--from-template` requires a skill directory (small breaking change), and Windows joins the CI matrix. ### Future Roadmap diff --git a/CHANGELOG.md b/CHANGELOG.md index a2b906a..53789a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [v0.3.0] — 2026-05-07 + +Platform registry rewrite, five new adapters, agent-instruction snippet +writer, and a focused breaking change to `--from-template`. + +### Breaking changes + +- **`skill create --from-template ` now requires a skill directory.** + A skill is a folder, so `--from-template` accepts only a directory containing + a `SKILL.md`. Passing a bare file (a `SKILL.md` or a body-only markdown file) + is rejected with a clear error pointing at the parent directory. The + previous behavior of treating a non-frontmatter markdown file as a raw body + is removed — wrap such bodies in a directory with a `SKILL.md` instead. ([#84]) + ### Added - **`skern init` can now write a skern usage snippet into agent instruction @@ -19,19 +33,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `--target ` overrides auto-discovery for explicit files, and `--print-instructions` emits the snippet to stdout without writing files. The `InitResult` JSON envelope grows an `instructions` field reporting - what was written. + what was written. ([#87]) - **Five new platform adapters: `cursor`, `gemini-cli`, `github-copilot`, `windsurf`, `continue`.** All five accept the same `--platform` flag, route installs to the platform's expected skill directory, and participate in `skern platform list`/`status` matrices. Path conventions follow [vercel-labs/skills](https://github.com/vercel-labs/skills#supported-agents). - ([#80]) + ([#81]) - **Declarative platform registry.** Adapters are now defined as one row in `internal/platform/spec.go` — a `Spec` carrying name, user dir, project dir, and home-relative detection paths. A single generic `Adapter` struct implements the `Platform` interface from any spec row, replacing the per-platform Go files (`claude.go`, `codex.go`, `opencode.go`). Adding a - platform is a one-line PR. ([#80]) + platform is a one-line PR. ([#81]) +- **Windows added to the CI matrix** — every PR now runs the test suite on + Windows in addition to macOS and Linux. ([#86]) +- **`--from-template` preserves template frontmatter and copies sibling + assets.** The template's `description`, `tags`, `metadata.author`, and + `metadata.version` are preserved on the new skill (#82) and every sibling + file or subdirectory (`references/`, `templates/`, `VENDORED.md`, …) is + copied alongside the new `SKILL.md` (#83). The CLI `` argument always + wins over the template's name; other flags override template values when + explicitly set, otherwise template values are preserved. ### Changed @@ -43,20 +66,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **CLI flag help and error messages enumerate the registered platforms dynamically** — adding a platform updates `--platform` help and the "unknown platform" error text without touching the CLI. -- **`skill create --from-template ` now requires a skill directory.** - A skill is a folder, so `--from-template` accepts only a directory containing - a `SKILL.md`. Passing a bare file (a `SKILL.md` or a body-only markdown file) - is rejected with a clear error that points at the parent directory. The - template's frontmatter (`description`, `tags`, `metadata.author`, - `metadata.version`) is preserved on the new skill (#82) and every sibling - file or subdirectory (e.g., `references/`, `templates/`, `VENDORED.md`) is - copied alongside the new `SKILL.md` (#83). The CLI `` argument always - wins over the template's `name`; other flags override template values when - explicitly set, otherwise template values are preserved. **Breaking:** the - previous behavior of treating a non-frontmatter markdown file as a raw body - is removed — wrap such bodies in a directory with a `SKILL.md` instead. - -[#80]: https://github.com/devrimcavusoglu/skern/issues/80 +- **Documentation site comprehensively refreshed** — eight platform pages, + reference covers `skill import` / `skill version` / `skill diff`, validation + page split into errors/warnings/hints, installation page covers all three + OSes, agent-setup leads with `init --instructions`. + +[v0.3.0]: https://github.com/devrimcavusoglu/skern/compare/v0.2.1...v0.3.0 +[#81]: https://github.com/devrimcavusoglu/skern/pull/81 +[#84]: https://github.com/devrimcavusoglu/skern/pull/84 +[#86]: https://github.com/devrimcavusoglu/skern/pull/86 +[#87]: https://github.com/devrimcavusoglu/skern/pull/87 ## [v0.2.1] — 2026-05-03 diff --git a/INSTALL.md b/INSTALL.md index 4275105..ae2f319 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -46,11 +46,11 @@ Override with the `SKERN_INSTALL_DIR` environment variable. ## Pin a specific version ```sh -SKERN_VERSION=v0.2.1 curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash +SKERN_VERSION=v0.3.0 curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash ``` ```powershell -$env:SKERN_VERSION = 'v0.2.1'; irm https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.ps1 | iex +$env:SKERN_VERSION = 'v0.3.0'; irm https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.ps1 | iex ``` ## Build from source diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 13d134a..1884a38 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -40,6 +40,7 @@ export default defineConfig({ { text: 'Installation', link: '/guide/installation' }, { text: 'Quick Start', link: '/guide/quick-start' }, { text: 'Agent Setup', link: '/guide/agent-setup' }, + { text: 'Writing Skills', link: '/writing-skills' }, ], }, ], @@ -73,6 +74,11 @@ export default defineConfig({ { text: 'Claude Code', link: '/platforms/claude-code' }, { text: 'Codex CLI', link: '/platforms/codex-cli' }, { text: 'OpenCode', link: '/platforms/opencode' }, + { text: 'Cursor', link: '/platforms/cursor' }, + { text: 'Gemini CLI', link: '/platforms/gemini-cli' }, + { text: 'GitHub Copilot', link: '/platforms/github-copilot' }, + { text: 'Windsurf', link: '/platforms/windsurf' }, + { text: 'Continue', link: '/platforms/continue' }, ], }, ], diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 17c6af1..3375620 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -5,17 +5,17 @@ Skern separates concerns into four layers: ``` Skill Author --> skern --> Registry --> Agent Runtime | - +-------+-------+ - | | | - Claude Codex OpenCode - Code CLI + +---------+---------+---------+---------+ + | | | | | | | + Claude Codex Open Cursor Gemini Copilot Continue / Windsurf / ... + Code CLI Code CLI ``` ## Layers ### Skill Definition -Metadata and behavior live in a single `SKILL.md` file. The file uses YAML frontmatter for structured fields (name, description, author, version, allowed-tools) and markdown body for the skill's instructions. +Metadata and behavior live in a single `SKILL.md` file. The file uses YAML frontmatter for structured fields (name, description, author, version, tags, allowed-tools) and markdown body for the skill's instructions. See [Skill Format](/concepts/skill-format) for the full specification. @@ -30,12 +30,20 @@ See [Registry](/concepts/registry) for details. ### Validation -Before a skill enters the registry, skern validates it against the [Agent Skills](https://agentskills.io) specification. This includes name format checks, description requirements, and overlap detection against existing skills. +Before a skill enters the registry, skern validates it against the [Agent Skills](https://agentskills.io) specification. This includes name format checks, description requirements, folder integrity (referenced files exist), and overlap detection against existing skills. Validation also surfaces stylistic **hints** (short body, vague description, missing trigger prefix) that don't affect validity. See [Validation](/reference/validation) and [Overlap Detection](/reference/overlap-detection) for rules and thresholds. ### Platform Adapters -Each supported platform has an adapter that knows where to install skills. Adapters copy the `SKILL.md` to the platform-specific directory, making the skill immediately available to the agent runtime. +Each supported platform has an adapter that knows where to install skills. Adapters copy the skill directory (`SKILL.md` plus any sibling files and subdirectories) to the platform-specific location, making the skill immediately available to the agent runtime. -See [Platform Adapters](/concepts/platform-adapters) for how adapters work. +Adapters are **declarative**: every supported platform is one row in `Specs` in [`internal/platform/spec.go`](https://github.com/devrimcavusoglu/skern/blob/main/internal/platform/spec.go). A single generic `Adapter` struct implements every platform's interface from the spec — no per-platform Go file is required. + +See [Platform Adapters](/concepts/platform-adapters) for how adapters work and the full path reference. + +## Dynamic Skill Loading + +Skern is not just a one-shot installer. The `install` and `uninstall` commands return a `capacity` block (installed count, per-scope threshold, headroom, over-budget flag) so agents can size their working set to a context budget. Pass `--enforce-budget` to refuse installs that would exceed the threshold. + +See the [Quick Start](/guide/quick-start#3-install-to-a-platform) for the workflow. diff --git a/docs/concepts/skill-format.md b/docs/concepts/skill-format.md index cda790e..30e42c3 100644 --- a/docs/concepts/skill-format.md +++ b/docs/concepts/skill-format.md @@ -1,63 +1,90 @@ # Skill Format -Skills follow the [Agent Skills](https://agentskills.io) open standard. Each skill is a single `SKILL.md` file with YAML frontmatter and a markdown body. +Skills follow the [Agent Skills](https://agentskills.io) open standard. Each skill is a directory containing a `SKILL.md` file with YAML frontmatter and a markdown body, plus any optional companion files. ## Structure ```markdown --- name: code-review -description: Review PRs for style and correctness +description: | + Use when reviewing pull requests for style and correctness. tags: - review - quality -version: 1.0.0 -author: - name: Jane Doe - type: human allowed-tools: - Read - Grep - Glob +metadata: + author: + name: Jane Doe + type: human # human | agent + platform: claude-code # only when type=agent + version: "1.0.0" + modified-by: # append-only provenance + - name: codex-cli + type: agent + platform: codex-cli + date: "2026-04-12T10:30:00Z" --- -## Instructions +## Overview -Review pull requests for: -- Code style consistency -- Correctness of logic -- Test coverage +1-2 sentence core principle of the skill. + +## When to Use + +- Triggering conditions and symptoms + +## Core Pattern + +The main technique or pattern (before/after for techniques). ``` ## Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| -| `name` | Yes | Skill name matching `[a-z0-9]+(-[a-z0-9]+)*`, 1-64 chars | -| `description` | Yes | What the skill does, max 1024 chars | -| `version` | No | Semantic version (e.g., `1.0.0`) | -| `author.name` | No | Author name | -| `author.type` | No | `human` or `agent` | -| `author.platform` | No | Platform name (e.g., `claude-code`) | +| `name` | Yes | Skill name matching `[a-z0-9]+(-[a-z0-9]+)*`, 1-64 chars. Must equal the directory name. | +| `description` | Yes | What the skill does — start with "Use when…". Max 1024 chars. | | `tags` | No | List of classification tags | -| `allowed-tools` | No | List of tools the skill may use | -| `modified-by` | No | Modification history entries | +| `allowed-tools` | No | Tools the skill may use. No empty entries. | +| `metadata.author.name` | No | Author name | +| `metadata.author.type` | No | `human` or `agent` | +| `metadata.author.platform` | No | Platform name (e.g. `claude-code`) — used when `type: agent` | +| `metadata.version` | No | Semantic version (e.g. `1.0.0`); defaults to `0.0.1` on `skill create` | +| `metadata.modified-by` | No | Append-only modification history (set via `skern skill edit --modified-by`) | + +`name` and `description` are the only hard requirements. The rest help discovery, validation, and provenance. ## Body The markdown body contains the skill's instructions. This is what the agent reads when the skill is activated. It must be non-empty. +The recommended body structure (also what `skern skill create` scaffolds) is: + +1. **Overview** — 1-2 sentence core principle +2. **When to Use** — triggering conditions +3. **Core Pattern** — the main technique +4. **Quick Reference** — scannable summary +5. **Common Mistakes** — frequent errors and fixes + +See [Writing Skills](/writing-skills) for details on what makes a discoverable, well-structured skill. + ## Author Provenance -Skills track author metadata and an optional `modified-by` history. `skern skill show` displays the full provenance chain when present, including editor name, type (human/agent), platform, and date. +Skills track an author and an append-only `modified-by` history. `skern skill show` prints the full provenance chain when present, including editor name, type (human/agent), platform, and date. `skern skill edit --modified-by ` adds a new entry without overwriting earlier ones. ## Folder Structure -Skills can include additional files alongside `SKILL.md` — helper scripts, templates, configuration files, and other assets. When a skill is installed to a platform, the entire directory is copied. +A skill is a directory. `SKILL.md` is the manifest; sibling files travel with it. ``` my-skill/ ├── SKILL.md +├── references/ +│ └── notes.md ├── scripts/ │ ├── convert.py │ └── setup.sh @@ -65,9 +92,9 @@ my-skill/ └── template.json ``` -The `scripts/` directory is language-agnostic — skills can include Python, shell, JavaScript, or any other scripts. The agent decides which language is appropriate for the skill. +When a skill is installed to a platform, the **entire directory** is copied. The `scripts/` directory is language-agnostic — skills can include Python, shell, JavaScript, or any other scripts. The agent decides which language is appropriate. -Use `skern skill show ` to see which files are bundled with a skill, and `skern skill validate ` to check that files referenced in the skill body actually exist. +`skern skill validate ` checks that files referenced in the body (via backticks or markdown links) actually exist in the skill directory. Missing references produce **warnings**, not errors. `skern skill show ` lists every file bundled with the skill. ## Creating Skills @@ -75,25 +102,30 @@ Use `skern skill create` to scaffold a new skill: ```sh skern skill create code-review \ - --description "Review PRs for style and correctness" \ + --description "Use when reviewing PRs for style and correctness" \ --author "Jane Doe" \ - --author-type human + --author-type human \ + --version 1.0.0 \ + --tags review,quality ``` -Or seed from another skill. `--from-template ` requires a **skill directory** -— a directory containing `SKILL.md` and any optional companion files -(`references/`, `templates/`, `VENDORED.md`, …). Skern parses the template's -frontmatter and copies every sibling into the new skill: +Or seed from another skill. `--from-template ` requires a **skill directory** — a directory containing `SKILL.md` and any optional companion files (`references/`, `templates/`, `VENDORED.md`, …). Skern parses the template's frontmatter and copies every sibling into the new skill: + +```sh +skern skill create code-review \ + --from-template ~/.skern/skills/source-template +``` + +A bare file path (a `SKILL.md` or a body-only markdown file) is rejected with an error pointing at the parent directory. The CLI `` argument always wins over the template's name; other flags (`--description`, `--tags`, `--author*`, `--version`) override template values when explicitly set, otherwise the template's values are preserved. + +## Importing Skills + +`skern skill import ` pulls an existing skill into the registry from a GitHub repository directory or gist: ```sh -# Seeds the new skill from an existing skill directory. SKILL.md frontmatter -# (description, tags, metadata.author, metadata.version) is preserved; all -# sibling files and subdirectories are copied alongside the new SKILL.md. -skern skill create code-review --from-template ~/.skern/skills/source-template +skern skill import https://github.com/owner/repo/tree/main/skills/code-review +skern skill import https://gist.github.com/ +skern skill import --name local-name --scope project ``` -A bare file path (e.g., a `SKILL.md` or a markdown body file) is rejected with -an error pointing you at the parent directory. The CLI `` argument -always wins over the template's `name`; other flags -(`--description`, `--tags`, `--author*`, `--version`) override template values -when explicitly set, otherwise the template's values are preserved. +Overlap detection runs on import too — pass `--force` to override a near-duplicate block. diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 31c8ff9..af9a1d6 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -3,7 +3,7 @@ ## Build ```sh -make build # Build binary with version/commit/date injected +make build # Build binary with version/commit/date injected via ldflags ``` The binary is placed at the repository root as `skern`. @@ -11,41 +11,86 @@ The binary is placed at the repository root as `skern`. ## Test ```sh -make test # Run unit tests -make test-v # Verbose test output -make test-cover # Generate coverage report -make test-smoke # Smoke & E2E tests against built binary +make test # Run unit tests +make test-v # Verbose test output +make test-cover # Generate coverage report (coverage.out + coverage.html) +make test-install # Run installer script tests +make test-smoke # Build binary and run smoke tests against it +make test-manual-setup # Set up manual test scenarios under /tmp +make test-manual-report # Generate the manual test pass/fail checklist +make test-manual-teardown # Clean up manual test environment ``` +Tests use stdlib `testing` plus `testify`. Integration tests that touch the filesystem must use `t.TempDir()`. Table-driven test patterns are preferred. + ## Lint & Format ```sh -make lint # Run golangci-lint -make fmt # Format code with gofmt +make lint # golangci-lint run +make fmt # gofmt -w . ``` +Linter config lives in `.golangci.yml`. + ## Clean ```sh -make clean # Remove build artifacts +make clean # Remove binary and coverage files ``` ## Project Structure ``` -cmd/skern/main.go # Entry point +cmd/skern/main.go # Entry point internal/ - cli/ # Cobra commands (root, version, init, completion, skill_*, platform_*) - skill/ # Domain: Skill struct, manifest parse/write, validation, scaffolding - overlap/ # Fuzzy name matching (Levenshtein) + description similarity scoring - registry/ # Filesystem CRUD over ~/.skern/skills/ and .skern/skills/ - platform/ # Adapters: Claude Code, Codex CLI, OpenCode - output/ # JSON/text output formatting (--json, --quiet) + cli/ # Cobra commands (root, version, init, completion, skill_*, platform_*) + instructions/ # Embedded snippets used by `skern init --instructions` + skill/ # Domain: Skill struct, manifest parse/write, validation, scaffolding, versioning, importer + overlap/ # Fuzzy name matching (Levenshtein) + description similarity scoring + registry/ # Filesystem CRUD over ~/.skern/skills/ and .skern/skills/ + platform/ # Declarative Spec table (spec.go) + a single generic Adapter (adapter.go) + output/ # JSON/text output formatting (--json, --quiet) +scripts/ + install.sh # Unix installer + install.ps1 # Windows PowerShell installer + install_test.sh # Installer tests + smoke_test.sh # Smoke tests for built binary +tests/manual/ # Agent-driven test scenarios (11 scenarios) +docs/ # VitePress documentation site ``` ## Conventions -- Tests are table-driven with `testify` and use `t.TempDir()` for temp dirs -- `cli/` package uses injectable `newRegistryFunc` / `newDetectorFunc` for test isolation -- Errors are wrapped with `fmt.Errorf("context: %w", err)` -- Dependencies: `cobra`, `yaml.v3`, `testify` +- `cli/` is wiring, flag parsing, and output. Business logic lives in `skill/`, `registry/`, `platform/`, `overlap/`. +- Adding a new platform = one row in `internal/platform/spec.go` plus one `Type` constant. No per-platform Go file. +- Errors are wrapped with `fmt.Errorf("context: %w", err)`. +- Exit codes: `0` success, `1` error, `2` validation failure. +- The `cli/` package uses injectable `NewRegistry` / `NewDetector` on `CommandContext` for test isolation. + +## Dependencies + +| Dependency | Purpose | +|------------|---------| +| `github.com/spf13/cobra` | CLI framework | +| `gopkg.in/yaml.v3` | YAML frontmatter parsing | +| `github.com/stretchr/testify` | Test assertions | + +## Issue Tracking + +Development is tracked using GitHub Issues via the `gh` CLI. Reference issues in commits as `#`. + +```sh +gh issue list # List open issues +gh issue create --title "Title" --body "" # Create a new issue +gh issue view # View issue details +``` + +## Branching + +Work is organized by milestone using feature branches: + +- **Branch naming**: `feature/m-` (e.g. `feature/m7-platform-registry`) +- **Created from**: `main` +- **Merged via**: pull request to `main` + +See [AGENTS.md](https://github.com/devrimcavusoglu/skern/blob/main/AGENTS.md) in the repo root for the complete development guide. diff --git a/docs/guide/agent-setup.md b/docs/guide/agent-setup.md index 9a3eaf2..5208d18 100644 --- a/docs/guide/agent-setup.md +++ b/docs/guide/agent-setup.md @@ -2,23 +2,57 @@ After installing skern, you can enable the **tool-forming loop** — a pattern where agents search for existing skills before creating new ones, keeping your skill set deduplicated and organized. -## Enable the Loop +## Recommended: `skern init --instructions` -Add a line to your project's `AGENTS.md` (or `CLAUDE.md`) so that agents know to use skern for skill management: +The fastest way to make your agent use skern correctly is to let `skern init` write its own usage snippet into your agent's instruction file: ```sh -echo 'Use skern to manage skills. Run `skern --help` for usage, `skern skill search ` to find existing skills before creating new ones.' >> AGENTS.md +skern init --instructions ``` -## How It Works +This auto-discovers `AGENTS.md`, `CLAUDE.md`, and `.claude/CLAUDE.md` under the current directory and writes a marker-wrapped block: + +```markdown + +## Skern (skill management) + +Use `skern` for ALL skill-related tasks — discovery, reading, creation, edits, removal. Run `skern --help` for the full command surface. + +``` + +Re-running `skern init --instructions` **updates the block in place** rather than appending a duplicate. + +### Add the search-before-create workflow + +```sh +skern init --instructions --tool-forming-loop +``` + +This appends a section that tells the agent to: + +1. Run `skern skill search ` first. +2. If a match scores ≥ 0.6, read it via `skern skill show ` and follow its body. +3. Only create a new skill (`skern skill create `) when nothing matches. + +### Other ways to drive `init` + +| Need | Flag | +|------|------| +| Write to a specific file (skips auto-discovery) | `--target ./MY_AGENT.md` (repeatable) | +| Print the snippet to stdout instead of writing | `--print-instructions` | +| Run non-interactively (CI, scripts) | Just pass the flags — prompts only fire on a TTY | + +When run on a TTY without `--instructions`/`--print-instructions`/`--target`, `skern init` asks whether to write the snippet and whether to include the tool-forming loop. Both default to **No**. Non-interactive runs honor flag values only. + +## How the Loop Works When an agent encounters a recurring task: -1. The agent reads the instruction from `AGENTS.md` -2. It runs `skern skill search ` to check for existing skills -3. If a matching skill exists, the agent reuses it -4. If no match is found, the agent creates a new skill with `skern skill create` -5. The new skill is immediately available for future sessions +1. The agent reads the snippet from `AGENTS.md`/`CLAUDE.md`. +2. It runs `skern skill search ` to check for existing skills. +3. If a matching skill exists, the agent reuses it. +4. If no match, the agent creates a new skill with `skern skill create`. +5. The new skill is immediately available for future sessions. ## JSON Mode for Agents @@ -26,24 +60,28 @@ Every skern command supports `--json` for machine-readable output: ```sh skern skill list --json +skern skill list --with-platforms --json # adds installed_on per skill skern skill search "review" --json skern skill show code-review --json +skern skill install code-review --platform claude-code --json ``` -This makes skern fully agent-operable — agents can parse responses and make decisions programmatically. +The `install`/`uninstall` JSON envelope carries a `skills[]` array (one entry per skill) and a top-level `capacity` block (`installed`, `threshold`, `headroom`, `over_budget`). Agents can react to capacity pressure without an extra query. -## Recommended Agent Instructions +## Manual Setup (Without `init`) -For more comprehensive agent integration, add these to your `AGENTS.md`: +If you'd rather hand-author the agent instructions, the bare minimum is: ```markdown ## Skill Management -- Use `skern` to manage reusable skills -- Before creating a new skill, search with `skern skill search ` -- Use `skern skill recommend ` to get suggestions before creating -- Always validate skills after creation: `skern skill validate ` -- Install to your current platform (the one you are running on), e.g. `skern skill install --platform claude-code` -- Multiple skills can be installed in one call: `skern skill install --platform

` -- Watch the `capacity` block in install/uninstall JSON output to manage your platform's working set; uninstall stale skills before adding new ones when capacity is tight +- Use `skern` to manage reusable skills. +- Before creating a new skill, run `skern skill search `. +- Use `skern skill recommend ` to get an explicit reuse-vs-extend-vs-create suggestion. +- Validate after creation: `skern skill validate `. +- Install to your current platform, e.g. `skern skill install --platform claude-code`. Each call targets one platform. +- Multiple skills install in one call: `skern skill install --platform

`. +- Watch the `capacity` block in install/uninstall JSON output. Uninstall stale skills before adding new ones when capacity is tight. ``` + +`skern init --instructions --print-instructions` will print exactly the snippet skern uses if you want to copy/customize it manually. diff --git a/docs/guide/index.md b/docs/guide/index.md index 9c4689f..b9eafa6 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,25 +1,27 @@ # Getting Started -Skern is a minimal, agent-first CLI for managing [Agent Skills](https://agentskills.io) across agentic development platforms. It provides a standardized lifecycle — create, validate, install, remove — for skills that work natively with **Claude Code**, **Codex CLI**, and **OpenCode**. +Skern is a minimal, agent-first CLI for managing [Agent Skills](https://agentskills.io) across agentic development platforms. It provides a standardized lifecycle — create, validate, install, remove — for skills that work natively with **Claude Code**, **Codex CLI**, **OpenCode**, **Cursor**, **Gemini CLI**, **GitHub Copilot**, **Windsurf**, and **Continue**. Skills follow the Agent Skills open standard (`SKILL.md` with YAML frontmatter) and are immediately usable by any compatible platform without adapters or format conversion. ## Why skern? -Modern AI coding tools (Claude Code, Codex CLI, OpenCode) lack a standardized skill management layer. Each defines skills in its own directory structure, with no shared tooling for creation, validation, deduplication, or cross-platform installation. +Modern AI coding tools each ship their own skill directory layout — `.claude/skills/`, `.agents/skills/`, `.opencode/skills/`, `.cursor/skills/`, and so on — with no shared tooling for creation, validation, deduplication, or cross-platform installation. Skern provides: - **Reusable skill definitions** — one `SKILL.md` per skill, portable across platforms -- **Project-scoped or system-scoped registration** — local skills for a repo, global skills for your machine +- **Project-scoped or user-scoped registration** — local skills for a repo, global skills for your machine - **Overlap detection** — fuzzy matching prevents skill duplication before it happens - **Cross-platform installation** — install to any supported platform with a single command +- **Dynamic skill loading** — batch install/uninstall plus per-platform capacity reporting so agents can size their working set to a context budget - **Agent-operable interface** — every command supports `--json`, enabling agents to manage their own skills ## Design Principles - **CLI-first** — terminal is the primary interface - **File-system native** — skills are files, registries are directories +- **Declarative platform registry** — adding a platform is a one-line append to `internal/platform/spec.go` - **Agent-agnostic** — works with any platform that reads `SKILL.md` - **Deterministic outputs** — same input, same result - **Minimal dependencies** — small binary, fast startup @@ -29,16 +31,22 @@ Skern provides: Skills should not live inside models. They should live in code. Versioned. Composable. Auditable. Portable. -## Roadmap +## What's Shipped -- [ ] Skill dependency resolution -- [ ] Versioned skill packages -- [ ] Remote skill registry -- [ ] Signed skill manifests -- [ ] Additional agent runtime adapters +The current release is **v0.3.0**. Major capabilities already in place: + +- Eight platform adapters (Claude Code, Codex CLI, OpenCode, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Continue) +- Cross-platform binaries for macOS, Linux, and Windows +- Skill versioning with semver (`skern skill version --bump major|minor|patch`) +- `skill diff` and `skill import` (URL / GitHub repo / gist) +- Stylistic lint hints in `skill validate` +- Batch install/uninstall and per-platform capacity reporting + +See the [CHANGELOG](https://github.com/devrimcavusoglu/skern/blob/main/CHANGELOG.md) for full release notes and the project's [GitHub issues](https://github.com/devrimcavusoglu/skern/issues) for the live roadmap (MCP server mode, remote catalog search, skill dependencies, etc.). ## Next Steps - [Installation](/guide/installation) — install skern on your machine - [Quick Start](/guide/quick-start) — create and install your first skill - [Agent Setup](/guide/agent-setup) — enable the tool-forming loop +- [Writing Skills](/writing-skills) — author skills agents can actually find and use diff --git a/docs/guide/installation.md b/docs/guide/installation.md index a9f0f54..f8c9dc3 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -1,26 +1,58 @@ # Installation -## Quick Install (Linux / macOS) +Skern ships pre-built binaries for macOS, Linux, and Windows. Pick the section that matches your operating system. + +The full canonical install guide lives at [INSTALL.md](https://github.com/devrimcavusoglu/skern/blob/main/INSTALL.md) in the repo — including custom install paths, manual install, and uninstall instructions. This page covers the most common paths. + +## macOS / Linux ```sh curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash ``` -To install a specific version: +The installer detects amd64/arm64, downloads the matching tarball, verifies its SHA-256 against the release's `checksums.txt`, and installs to `~/.local/bin/skern` by default. + +## Windows (PowerShell) + +```powershell +irm https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.ps1 | iex +``` + +Installs to `%LOCALAPPDATA%\skern\bin\skern.exe`. If your PowerShell execution policy blocks the script: + +```powershell +powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.ps1 | iex" +``` + +## Pin a Version + +Set `SKERN_VERSION` before running the installer: ```sh -SKERN_VERSION=v0.0.1 curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash +SKERN_VERSION=v0.3.0 curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash +``` + +```powershell +$env:SKERN_VERSION = 'v0.3.0'; irm https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.ps1 | iex ``` -## Go Install +## Custom Install Directory -Requires Go 1.25+. +Both installers honor `SKERN_INSTALL_DIR`: + +```sh +SKERN_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/devrimcavusoglu/skern/main/scripts/install.sh | bash +``` + +## From Source (Go 1.25+) ```sh go install github.com/devrimcavusoglu/skern/cmd/skern@latest ``` -## Build from Source +When built this way, version info falls back to `runtime/debug.ReadBuildInfo` since ldflags aren't injected. + +## Build Locally ```sh git clone https://github.com/devrimcavusoglu/skern.git @@ -28,10 +60,26 @@ cd skern make build ``` -The binary will be placed in the repository root as `skern`. Move it to a directory in your `PATH` to use it globally. +The binary is placed at the repository root as `skern`. Move it onto your `PATH` to use it globally. + +## Manual Install + +Download the archive for your platform from [the releases page](https://github.com/devrimcavusoglu/skern/releases/latest) and extract the binary. Archive naming: + +- `skern__darwin_.tar.gz` +- `skern__linux_.tar.gz` +- `skern__windows_.zip` + +`` is `amd64` or `arm64`. Each release also publishes `checksums.txt` with SHA-256 sums. ## Verify Installation ```sh -skern version +skern --version ``` + +If the command is not found, the install directory is not yet on your `PATH`. The shell installer prints PATH instructions for your shell at the end — follow those, then open a new shell. + +## Uninstall + +Delete the binary at the install location. The installer does not modify any other files. diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 62c36f4..2493f52 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -8,15 +8,23 @@ This walkthrough creates a skill and installs it to a platform in under a minute skern init ``` -This creates a `.skern/` directory in your project for project-scoped skills. +This creates a `.skern/skills/` directory in your project for project-scoped skills. It is idempotent — safe to re-run. + +To also drop a skern usage snippet into your agent's instruction file (`AGENTS.md`, `CLAUDE.md`, or `.claude/CLAUDE.md`) so the agent uses skern for skill management: + +```sh +skern init --instructions +``` + +Add `--tool-forming-loop` to include the search-before-create workflow section. The snippet is wrapped in `` / `` markers, so re-running updates the block in place. See [`skern init`](/reference/commands#skern-init) for all flags. ## 2. Create a Skill ```sh -skern skill create code-review --description "Review PRs for style and correctness" +skern skill create code-review --description "Use when reviewing pull requests for style and correctness" ``` -This scaffolds a `SKILL.md` file in the registry with the given name and description. +This scaffolds a `SKILL.md` file in the registry with the given name and description. Overlap detection runs automatically — see [Overlap Detection](/reference/overlap-detection). ## 3. Install to a Platform @@ -26,32 +34,50 @@ Install to Claude Code: skern skill install code-review --platform claude-code ``` -Each invocation targets one platform. To install to multiple platforms, loop the call: +Each invocation targets exactly one platform — `--platform all` is not accepted. To deploy across multiple platforms, loop the call: ```sh -for p in claude-code codex-cli opencode; do +for p in claude-code codex-cli opencode cursor gemini-cli; do skern skill install code-review --platform "$p" done ``` -You can also install several skills at once: +Multiple skill names can be installed in a single call: ```sh skern skill install code-review test-runner deploy-checker --platform claude-code ``` +The response includes a `capacity` block reporting the installed-skill count, threshold, and remaining headroom for the platform. Pass `--enforce-budget` to refuse the install when the count would exceed the threshold. + ## 4. List Installed Skills ```sh skern skill list ``` +Add `--with-platforms` to surface per-skill installation state across detected platforms: + +```sh +skern skill list --with-platforms +``` + ## 5. Search Before Creating Avoid duplicates by searching first: ```sh skern skill search "review" +skern skill recommend "review pull requests" # decides reuse vs. extend vs. create +``` + +## 6. Diff Before Editing + +Compare a registry skill against its installed copy on a platform, or two registry skills: + +```sh +skern skill diff code-review --platform claude-code +skern skill diff code-review code-review-strict ``` ## What's Next? @@ -59,3 +85,4 @@ skern skill search "review" - [Agent Setup](/guide/agent-setup) — enable agents to manage skills automatically - [CLI Reference](/reference/commands) — full command documentation - [Skill Format](/concepts/skill-format) — understand the `SKILL.md` structure +- [Writing Skills](/writing-skills) — write skills agents can find and reuse diff --git a/docs/index.md b/docs/index.md index c161234..e2afd91 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,8 +24,8 @@ features: title: Agent Skills Spec Compliance details: Reads and writes SKILL.md files directly following the Agent Skills open standard — no proprietary format. - icon: "\U0001F517" - title: Platform Adapters - details: Install skills to Claude Code, Codex CLI, or OpenCode with a single command. + title: Eight Platform Adapters + details: Install skills to Claude Code, Codex CLI, OpenCode, Cursor, Gemini CLI, GitHub Copilot, Windsurf, or Continue with a single command. - icon: "\U0001F504" title: Tool-Forming Loop details: Agents can search for existing skills and scaffold new ones, turning recurring needs into reusable capabilities. diff --git a/docs/platforms/claude-code.md b/docs/platforms/claude-code.md index 1260b96..a636263 100644 --- a/docs/platforms/claude-code.md +++ b/docs/platforms/claude-code.md @@ -1,6 +1,6 @@ # Claude Code -[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's AI coding assistant that works in the terminal. It reads skills from the `.claude/skills/` directory. +[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's terminal-based AI coding assistant. It reads skills from the `.claude/skills/` directory. ## Skill Paths @@ -9,14 +9,16 @@ | User-level | `~/.claude/skills//SKILL.md` | | Project-level | `.claude/skills//SKILL.md` | +Claude Code uses dedicated user and project directories — it does not share `.agents/skills/`. + ## Install a Skill ```sh -# Project-level (default) +# User-level (default scope is user) skern skill install code-review --platform claude-code -# User-level -skern skill install code-review --platform claude-code --scope user +# Project-level +skern skill install code-review --platform claude-code --scope project ``` ## Uninstall a Skill @@ -27,8 +29,8 @@ skern skill uninstall code-review --platform claude-code ## Detection -Skern detects Claude Code by checking for the presence of `.claude/` in the current project or `~/.claude/` at the user level. +Skern detects Claude Code by the presence of `~/.claude/`. ## How Skills Work in Claude Code -When Claude Code starts a session, it reads all `SKILL.md` files from the skills directories. Skills become available as capabilities that Claude can use during the session. The skill's markdown body serves as instructions that Claude follows when the skill is activated. +When Claude Code starts a session, it reads `SKILL.md` files from the skills directory. Skills become available as capabilities Claude can use during the session — the skill's markdown body serves as instructions Claude follows when the skill is activated. diff --git a/docs/platforms/codex-cli.md b/docs/platforms/codex-cli.md index 212a4a6..1c3e195 100644 --- a/docs/platforms/codex-cli.md +++ b/docs/platforms/codex-cli.md @@ -9,14 +9,20 @@ | User-level | `~/.agents/skills//SKILL.md` | | Project-level | `.agents/skills//SKILL.md` | +The project-level path is shared with `cursor`, `gemini-cli`, and `github-copilot`. A skill installed there is visible to every agent that reads from `.agents/skills/` — see [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory). + +::: tip +The user-level path stays at `~/.agents/skills/` for compatibility with skern's original layout. Detection covers both `~/.codex/` and `~/.agents/`. +::: + ## Install a Skill ```sh -# Project-level (default) +# User-level (default scope is user) skern skill install code-review --platform codex-cli -# User-level -skern skill install code-review --platform codex-cli --scope user +# Project-level +skern skill install code-review --platform codex-cli --scope project ``` ## Uninstall a Skill @@ -27,7 +33,7 @@ skern skill uninstall code-review --platform codex-cli ## Detection -Skern detects Codex CLI by checking for `~/.codex/` (preferred) or `~/.agents/` at the user level. The `.agents/skills/` project directory is shared with several other agents (cursor, gemini-cli, github-copilot) — see [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory). +Skern detects Codex CLI by the presence of `~/.codex/` (preferred) or `~/.agents/`. ## How Skills Work in Codex CLI diff --git a/docs/platforms/continue.md b/docs/platforms/continue.md new file mode 100644 index 0000000..6c8a0c1 --- /dev/null +++ b/docs/platforms/continue.md @@ -0,0 +1,29 @@ +# Continue + +[Continue](https://continue.dev/) is an open-source AI code assistant. Skern installs skills into its skills directory. + +## Skill Paths + +| Scope | Path | +|-------|------| +| User-level | `~/.continue/skills//SKILL.md` | +| Project-level | `.continue/skills//SKILL.md` | + +Continue uses dedicated user and project directories — it does not share the `.agents/skills/` directory. + +## Install a Skill + +```sh +skern skill install code-review --platform continue +skern skill install code-review --platform continue --scope project +``` + +## Uninstall a Skill + +```sh +skern skill uninstall code-review --platform continue +``` + +## Detection + +Skern detects Continue by the presence of `~/.continue/`. diff --git a/docs/platforms/cursor.md b/docs/platforms/cursor.md new file mode 100644 index 0000000..4c0e343 --- /dev/null +++ b/docs/platforms/cursor.md @@ -0,0 +1,32 @@ +# Cursor + +[Cursor](https://www.cursor.com/) is an AI-first code editor. Skern installs skills into its skills directory. + +## Skill Paths + +| Scope | Path | +|-------|------| +| User-level | `~/.cursor/skills//SKILL.md` | +| Project-level | `.agents/skills//SKILL.md` | + +The project-level path is shared with `codex-cli`, `gemini-cli`, and `github-copilot`. A skill installed at `.agents/skills/` is visible to every agent that reads from there — see [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory). + +## Install a Skill + +```sh +# User-level (default scope is user) +skern skill install code-review --platform cursor + +# Project-level +skern skill install code-review --platform cursor --scope project +``` + +## Uninstall a Skill + +```sh +skern skill uninstall code-review --platform cursor +``` + +## Detection + +Skern detects Cursor by the presence of `~/.cursor/`. The shared `.agents/skills/` project directory does not by itself signal Cursor — detection keys on the user-level config dir. diff --git a/docs/platforms/gemini-cli.md b/docs/platforms/gemini-cli.md new file mode 100644 index 0000000..9a18f96 --- /dev/null +++ b/docs/platforms/gemini-cli.md @@ -0,0 +1,29 @@ +# Gemini CLI + +[Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's command-line AI agent. Skern installs skills into its skills directory. + +## Skill Paths + +| Scope | Path | +|-------|------| +| User-level | `~/.gemini/skills//SKILL.md` | +| Project-level | `.agents/skills//SKILL.md` | + +The project-level path is shared with `codex-cli`, `cursor`, and `github-copilot`. See [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory). + +## Install a Skill + +```sh +skern skill install code-review --platform gemini-cli +skern skill install code-review --platform gemini-cli --scope project +``` + +## Uninstall a Skill + +```sh +skern skill uninstall code-review --platform gemini-cli +``` + +## Detection + +Skern detects Gemini CLI by the presence of `~/.gemini/`. diff --git a/docs/platforms/github-copilot.md b/docs/platforms/github-copilot.md new file mode 100644 index 0000000..f8f5f0b --- /dev/null +++ b/docs/platforms/github-copilot.md @@ -0,0 +1,29 @@ +# GitHub Copilot + +[GitHub Copilot](https://github.com/features/copilot) is GitHub's AI coding assistant. Skern installs skills into its skills directory. + +## Skill Paths + +| Scope | Path | +|-------|------| +| User-level | `~/.copilot/skills//SKILL.md` | +| Project-level | `.agents/skills//SKILL.md` | + +The project-level path is shared with `codex-cli`, `cursor`, and `gemini-cli`. See [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory). + +## Install a Skill + +```sh +skern skill install code-review --platform github-copilot +skern skill install code-review --platform github-copilot --scope project +``` + +## Uninstall a Skill + +```sh +skern skill uninstall code-review --platform github-copilot +``` + +## Detection + +Skern detects GitHub Copilot by the presence of `~/.copilot/`. diff --git a/docs/platforms/index.md b/docs/platforms/index.md index d14eb91..d3dfd6d 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -1,42 +1,51 @@ # Supported Platforms -Skern ships adapters for the most common agentic development platforms. Each adapter knows where its platform stores user-level and project-level skills, copies skills into place, and reports which platforms are installed on the host. +Skern ships eight adapters out of the box. Each adapter knows where its platform stores user-level and project-level skills, copies skills into place, and reports whether the platform is installed on the current host. -The set is driven by a declarative registry in `internal/platform/spec.go` — adding a new platform is a one-line append (see [Platform Adapters](/concepts/platform-adapters#adding-a-platform)). +The set is driven by a declarative registry in [`internal/platform/spec.go`](https://github.com/devrimcavusoglu/skern/blob/main/internal/platform/spec.go) — adding a new platform is a one-line append (see [Platform Adapters › Adding a Platform](/concepts/platform-adapters#adding-a-platform)). ## Path Reference | Adapter name | User-level skills | Project-level skills | -|--------------|--------------------|----------------------| -| `claude-code` | `~/.claude/skills/` | `.claude/skills/` | -| `codex-cli` | `~/.agents/skills/` | `.agents/skills/` | -| `opencode` | `~/.config/opencode/skills/` | `.opencode/skills/` | -| `cursor` | `~/.cursor/skills/` | `.agents/skills/` | -| `gemini-cli` | `~/.gemini/skills/` | `.agents/skills/` | -| `github-copilot` | `~/.copilot/skills/` | `.agents/skills/` | -| `windsurf` | `~/.codeium/windsurf/skills/` | `.windsurf/skills/` | -| `continue` | `~/.continue/skills/` | `.continue/skills/` | +|--------------|-------------------|----------------------| +| [`claude-code`](/platforms/claude-code) | `~/.claude/skills/` | `.claude/skills/` | +| [`codex-cli`](/platforms/codex-cli) | `~/.agents/skills/` | `.agents/skills/` | +| [`opencode`](/platforms/opencode) | `~/.config/opencode/skills/` | `.opencode/skills/` | +| [`cursor`](/platforms/cursor) | `~/.cursor/skills/` | `.agents/skills/` | +| [`gemini-cli`](/platforms/gemini-cli) | `~/.gemini/skills/` | `.agents/skills/` | +| [`github-copilot`](/platforms/github-copilot) | `~/.copilot/skills/` | `.agents/skills/` | +| [`windsurf`](/platforms/windsurf) | `~/.codeium/windsurf/skills/` | `.windsurf/skills/` | +| [`continue`](/platforms/continue) | `~/.continue/skills/` | `.continue/skills/` | -Several platforms share `.agents/skills/` as their project directory — a skill installed there is visible to every agent that reads from it. See [Platform Adapters](/concepts/platform-adapters#shared-project-directory) for the implications on capacity reporting and detection. +Path conventions track [vercel-labs/skills](https://github.com/vercel-labs/skills#supported-agents), the closest thing to a community standard for Agent Skills directory layout. -## Auto-detection +`codex-cli`, `cursor`, `gemini-cli`, and `github-copilot` all use `.agents/skills/` as their project-level directory. A skill installed there is visible to every agent that reads from it — that's intentional and matches the upstream convention. See [Platform Adapters › Shared project directory](/concepts/platform-adapters#shared-project-directory) for the implications on capacity reporting and detection. -`skern platform list` reports which adapters appear installed on the current host. Detection is per-platform: each adapter checks its own user-level config dir (e.g. `~/.cursor`, `~/.gemini`, `~/.copilot`) so platforms that share a project directory are still distinguished. +## Auto-Detection + +`skern platform list` reports which adapters appear installed on the current host. Detection is per-platform: each adapter checks its own user-level config dir (`~/.claude`, `~/.cursor`, `~/.gemini`, `~/.copilot`, `~/.codex`, …) so platforms that share a project directory are still distinguished. ## Feature Comparison -| Feature | skern | Manual Folder Skills | AI Tool Built-in | +| Feature | skern | Manual folder skills | AI tool built-in | |---------|-------|----------------------|------------------| | System-wide registry | Yes | No | No | | Cross-platform install | Yes | No | No | | Overlap detection | Yes | No | No | +| Per-platform capacity reporting | Yes | No | No | +| Validation (errors / warnings / hints) | Yes | No | No | +| Versioning (semver, bump, diff) | Yes | No | No | +| Skill import (URL / GitHub / gist) | Yes | No | No | | CLI-first | Yes | Partial | No | | Agent-agnostic | Yes | Partial | No | -| Validation | Yes | No | No | -| Versioning | Planned | No | No | ## Quick Links -- [Claude Code](/platforms/claude-code) — Anthropic's AI coding assistant -- [Codex CLI](/platforms/codex-cli) — OpenAI's terminal-based coding agent -- [OpenCode](/platforms/opencode) — Open-source AI coding tool +- [Claude Code](/platforms/claude-code) — Anthropic's terminal AI assistant +- [Codex CLI](/platforms/codex-cli) — OpenAI's terminal coding agent +- [OpenCode](/platforms/opencode) — open-source AI coding tool +- [Cursor](/platforms/cursor) — AI-first code editor +- [Gemini CLI](/platforms/gemini-cli) — Google's command-line agent +- [GitHub Copilot](/platforms/github-copilot) — GitHub's AI coding assistant +- [Windsurf](/platforms/windsurf) — Codeium's agentic IDE +- [Continue](/platforms/continue) — open-source AI code assistant diff --git a/docs/platforms/opencode.md b/docs/platforms/opencode.md index 0560095..1657a46 100644 --- a/docs/platforms/opencode.md +++ b/docs/platforms/opencode.md @@ -9,14 +9,16 @@ | User-level | `~/.config/opencode/skills//SKILL.md` | | Project-level | `.opencode/skills//SKILL.md` | +OpenCode uses dedicated user and project directories — it does not share `.agents/skills/`. + ## Install a Skill ```sh -# Project-level (default) +# User-level (default scope is user) skern skill install code-review --platform opencode -# User-level -skern skill install code-review --platform opencode --scope user +# Project-level +skern skill install code-review --platform opencode --scope project ``` ## Uninstall a Skill @@ -27,7 +29,7 @@ skern skill uninstall code-review --platform opencode ## Detection -Skern detects OpenCode by checking for the presence of `.opencode/` in the current project or `~/.config/opencode/` at the user level. +Skern detects OpenCode by the presence of `~/.config/opencode/`. ## How Skills Work in OpenCode diff --git a/docs/platforms/windsurf.md b/docs/platforms/windsurf.md new file mode 100644 index 0000000..0570a9b --- /dev/null +++ b/docs/platforms/windsurf.md @@ -0,0 +1,29 @@ +# Windsurf + +[Windsurf](https://windsurf.com/) is Codeium's agentic IDE. Skern installs skills into its skills directory. + +## Skill Paths + +| Scope | Path | +|-------|------| +| User-level | `~/.codeium/windsurf/skills//SKILL.md` | +| Project-level | `.windsurf/skills//SKILL.md` | + +Windsurf does not share the `.agents/skills/` project directory with other adapters — its project skills live at `.windsurf/skills/`. + +## Install a Skill + +```sh +skern skill install code-review --platform windsurf +skern skill install code-review --platform windsurf --scope project +``` + +## Uninstall a Skill + +```sh +skern skill uninstall code-review --platform windsurf +``` + +## Detection + +Skern detects Windsurf by the presence of `~/.codeium/windsurf/` or `~/.windsurf/`. diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 73e464e..127f913 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -4,31 +4,51 @@ ``` skern init # Initialize .skern/ in current project +skern version # Print version, commit, build date +skern completion [bash|zsh|fish] # Generate shell completions + +# Registry commands (manage skills in skern) skern skill create # Scaffold a new skill +skern skill import # Import a skill from URL/git/gist skern skill edit # Edit skill metadata or body -skern skill search # Search skills by name/description -skern skill recommend # Recommend: reuse, extend, or create +skern skill remove # Remove skill from registry skern skill list [--scope user|project|all] # List skills in registry skern skill show # Display skill details +skern skill search # Search skills by name/description skern skill validate # Validate against Agent Skills spec -skern skill remove # Remove skill from registry +skern skill version [--bump LEVEL] # Show or bump a skill's version +skern skill diff [name-b] # Compare two skills (or registry vs platform) +skern skill recommend # Reuse / extend / create suggestion + +# Platform commands (deploy skills to platforms) skern skill install ... --platform

# Install one or more skills to platform -skern skill uninstall ... --platform

# Remove one or more skills from platform +skern skill uninstall ... --platform

# Remove one or more skills from platform skern platform list # List detected platforms skern platform status # Skill x platform installation matrix -skern completion [bash|zsh|fish] # Generate shell completions -skern version # Print version info ``` +`skern skill --help` groups subcommands into **Registry commands** (skills in skern) and **Platform commands** (skills deployed to a platform). The same split is reflected above. + +## Global Flags + +| Flag | Description | +|------|-------------| +| `--json` | Output in JSON format. Available on every command. | +| `--quiet` | Suppress non-essential output. | + +Most commands also accept `--scope user|project|all`. Exit codes: `0` success, `1` error, `2` validation failure. + ## `skern init` -Initialize the `.skern/` directory in the current project (creates the project-scoped skill registry). Optionally writes a skern usage snippet into agent instruction files (`AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`) so the agent uses skern for all skill-related tasks instead of reading platform-native skill directories. +Initialize the `.skern/` directory in the current project (creates the project-scoped skill registry). Idempotent — safe to re-run. + +Optionally writes a skern usage snippet into agent instruction files (`AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`) so the agent uses skern for all skill-related tasks instead of reading platform-native skill directories. ```sh skern init # creates .skern/ only (default) -skern init --instructions # also writes the usage snippet to discovered agent config files +skern init --instructions # also writes the snippet to discovered agent config files skern init --instructions --tool-forming-loop # adds the search-before-create workflow section -skern init --target ./MY_AGENT.md # write to a specific file (skips auto-discovery) +skern init --target ./MY_AGENT.md # write to a specific file (skips auto-discovery; repeatable) skern init --print-instructions # print the snippet to stdout instead of writing files ``` @@ -36,18 +56,18 @@ skern init --print-instructions # print the snippet to stdout inst | Flag | Description | |------|-------------| -| `--instructions` | Write the skern usage snippet to discovered agent config files (`AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`). Default: off. | +| `--instructions` | Write the skern usage snippet to discovered agent config files. Default: off. | | `--tool-forming-loop` | Include the tool-forming-loop section (search-before-create workflow). Default: off. | | `--target ` | Explicit instruction file path. Repeatable. Disables auto-discovery when set. | | `--print-instructions` | Print the rendered snippet to stdout instead of writing files. | -The instruction snippet is wrapped in `` / `` markers, so re-running `skern init --instructions` updates the block in place rather than appending duplicates. +The instruction snippet is wrapped in `` / `` markers so re-running `skern init --instructions` updates the block in place rather than appending a duplicate. -When run on a TTY without `--json` or instruction flags, `skern init` prompts the user for both choices (write instructions? include tool-forming loop?). Default to **No** for both. Non-interactive runs (CI, scripts, `--json`) honor flag values only — no prompts. +When run on a TTY without `--json` or any of the instruction flags, `skern init` prompts for both choices (write instructions? include tool-forming loop?). Default to **No** for both. Non-interactive runs (CI, scripts, `--json`) honor flag values only — no prompts. ## `skern skill create` -Scaffold a new `SKILL.md` file in the registry. +Scaffold a new skill in the registry. ```sh skern skill create [flags] @@ -55,45 +75,65 @@ skern skill create [flags] **Flags:** -| Flag | Description | -|------|-------------| -| `--author` | Author name | -| `--author-type` | `human` or `agent` | -| `--author-platform` | Platform name (e.g., `claude-code`) | -| `--description` | Skill description | -| `--tags` | Comma-separated list of tags | -| `--scope` | `user` or `project` (default: `user`) | -| `--force` | Bypass overlap block | -| `--from-template

` | Seed from a skill directory containing `SKILL.md` and optional companion files (see below) | +| Flag | Default | Description | +|------|---------|-------------| +| `--description` | — | Skill description (start with "Use when…") | +| `--author` | — | Author name | +| `--author-type` | `human` | `human` or `agent` | +| `--author-platform` | — | Platform name (e.g. `claude-code`) — used with `agent` author type | +| `--tags` | — | Comma-separated list of tags | +| `--version` | `0.0.1` | Initial semver version | +| `--scope` | `user` | `user` or `project` | +| `--force` | `false` | Bypass overlap block | +| `--from-template ` | — | Seed from a skill directory containing `SKILL.md` plus optional companion files | -Overlap detection runs automatically during creation. See [Overlap Detection](/reference/overlap-detection) for details. +Overlap detection runs automatically. Validation runs as warnings (does not block). Skill count thresholds emit warnings at >= 20 (project) / >= 50 (user). ### `--from-template` -`--from-template ` accepts a **skill directory** — a directory containing -a `SKILL.md` plus any optional companion files. Skern parses the template's -frontmatter and recursively copies every sibling file and subdirectory -(`references/`, `templates/`, `VENDORED.md`, …) into the new skill. +`--from-template ` accepts a **skill directory** — a directory containing a `SKILL.md` plus any optional companion files. Skern parses the template's frontmatter and recursively copies every sibling file and subdirectory (`references/`, `templates/`, `VENDORED.md`, …) into the new skill. -Anything else is rejected with a clear error: +Anything else is rejected: - `--from-template ` → "must point to a skill directory containing a SKILL.md file … pass the parent directory instead" - `--from-template ` → "directory has no SKILL.md; a skill template must be a directory containing a SKILL.md file" -The new skill's `name` is always taken from the CLI argument. Other CLI -flags (`--description`, `--tags`, `--author*`, `--version`) override the -template's values when explicitly set; otherwise the template's values are -preserved. +The new skill's `name` is always taken from the CLI argument. Other CLI flags (`--description`, `--tags`, `--author*`, `--version`) override template values when explicitly set; otherwise the template's values are preserved. + +## `skern skill import` + +Import a skill from a remote source into the registry. + +```sh +skern skill import +``` + +Supports GitHub repository directories and gists: + +```sh +skern skill import https://github.com/owner/repo/tree/main/skills/code-review +skern skill import https://gist.github.com/ +``` + +**Flags:** + +| Flag | Default | Description | +|------|---------|-------------| +| `--scope` | `user` | `user` or `project` | +| `--name` | — | Override the skill name from the imported manifest | +| `--force` | `false` | Overwrite if the skill already exists and bypass overlap block | + +The skill's directory contents (`SKILL.md` plus siblings discoverable via the source) are fetched and written into the registry. Overlap detection runs against existing skills. ## `skern skill edit` -Edit a skill's metadata fields or open the body in an editor. +Edit a skill's metadata fields, or open the body in `$EDITOR` (defaults to `vi`). ```sh skern skill edit [flags] ``` -When called with field flags, the specified fields are updated directly. When called without field flags, the skill body is opened in `$EDITOR` (defaults to `vi`). +When called with field flags, the specified fields are updated directly. When called without field flags, the skill body is opened in your editor. **Flags:** @@ -105,88 +145,129 @@ When called with field flags, the specified fields are updated directly. When ca | `--author-type` | `human` or `agent` | | `--author-platform` | Platform name | | `--version` | New version string | -| `--modified-by` | Name of modifier (appends to `modified-by` list) | +| `--modified-by` | Name of modifier (appends to the `modified-by` list) | | `--modified-by-type` | `human` or `agent` | -| `--modified-by-platform` | Platform name for modifier | +| `--modified-by-platform` | Platform name for the modifier | -## `skern skill search` +`--modified-by` is **append-only** — every edit can record provenance without overwriting earlier entries. -Search skills by name or description. +## `skern skill remove` + +Remove a skill from the registry. Does not affect platform installs. ```sh -skern skill search [flags] +skern skill remove [--scope user|project] ``` -**Flags:** +To remove a skill from a platform without removing it from the registry, use `skern skill uninstall`. -| Flag | Description | -|------|-------------| -| `--tag` | Filter results to skills with this tag | - -## `skern skill recommend` +## `skern skill list` -Get recommendations on whether to reuse, extend, or create a skill. +List skills in the registry. ```sh -skern skill recommend [flags] +skern skill list [--scope user|project|all] [flags] ``` **Flags:** -| Flag | Description | -|------|-------------| -| `--name` | Agent-suggested skill name | -| `--threshold` | Minimum relevance score (default: 0.3) | -| `--scope` | `user`, `project`, or `all` | +| Flag | Default | Description | +|------|---------|-------------| +| `--scope` | `all` | `user`, `project`, or `all` | +| `--tag` | — | Filter results to skills with this tag | +| `--with-platforms` | `false` | Include `installed_on` per skill (the detected platforms where the skill is installed at the same scope) | -## `skern skill list` +Also runs pairwise overlap detection across all listed skills and appends a "Potential duplicates" section when matches are found (score >= 0.6). In `--json` mode they appear in the `duplicates` array. -List all skills in the registry. +Skills that cannot be parsed are reported as parse warnings rather than silently skipped — text mode prints `WARNING:` lines, `--json` mode populates the `parse_warnings` array. -```sh -skern skill list [--scope user|project|all] [flags] -``` +When `--with-platforms` is set the JSON output contains an `installed_on` array on every skill — empty for skills not installed on any detected platform. Without the flag the field is omitted entirely so consumers can distinguish "queried, none" from "not queried". -**Flags:** +## `skern skill show` -| Flag | Description | -|------|-------------| -| `--scope` | `user`, `project`, or `all` | -| `--tag` | Filter results to skills with this tag | -| `--with-platforms` | Include `installed_on` per-skill: the detected platforms where the skill is currently installed at the same scope | +Display full details for a skill, including author provenance, modification history, and bundled files. -Also runs pairwise overlap detection across all listed skills and appends a "Potential duplicates" section when matches are found (score >= 0.6). In `--json` mode, these appear in the `duplicates` array. +```sh +skern skill show [--scope user|project] +``` -Skills that cannot be parsed are reported as parse warnings rather than silently skipped. In text mode these appear as warning lines; in `--json` mode they appear in the `parse_warnings` array. +## `skern skill search` -When `--with-platforms` is set, the JSON output contains an `installed_on` array on every skill — empty for skills not installed on any detected platform. Without the flag the field is omitted entirely so consumers can distinguish "queried, none" from "not queried". +Search skills by name or description. -## `skern skill show` +```sh +skern skill search [--tag ] +``` + +## `skern skill recommend` -Display full details for a skill, including author provenance and modification history. +Get an explicit recommendation: **REUSE** an existing skill, **EXTEND** one, or **CREATE** a new one. ```sh -skern skill show +skern skill recommend [flags] ``` +Thresholds: score ≥ 0.8 → REUSE; score ≥ 0.5 → EXTEND; below → CREATE. + +**Flags:** + +| Flag | Default | Description | +|------|---------|-------------| +| `--name` | — | Agent-suggested skill name (used in CREATE recommendation) | +| `--threshold` | `0.3` | Minimum relevance score to include in results | +| `--scope` | `all` | `user`, `project`, or `all` | + ## `skern skill validate` Validate a skill against the Agent Skills spec. ```sh -skern skill validate +skern skill validate [--scope user|project] ``` -See [Validation](/reference/validation) for the full list of checks. +Reports errors, warnings, and stylistic hints. Exit code is `2` when errors are present. See [Validation](/reference/validation) for the full list of checks. -## `skern skill remove` +## `skern skill version` + +Show or bump a skill's semver version. + +```sh +skern skill version # show current version +skern skill version --bump patch # 0.0.1 -> 0.0.2 +skern skill version --bump minor # 0.0.2 -> 0.1.0 +skern skill version --bump major # 0.1.0 -> 1.0.0 +``` + +**Flags:** + +| Flag | Description | +|------|-------------| +| `--scope` | `user` or `project` | +| `--bump` | `patch`, `minor`, or `major` | + +Without `--bump`, prints the current version. The JSON envelope returns `previous_version` and `bumped: true` after a bump. -Remove a skill from the registry. +## `skern skill diff` + +Compare two skills side by side. With one argument, compares a registry skill against its installed copy on a platform. With two arguments, compares two registry skills. ```sh -skern skill remove +# Registry vs installed +skern skill diff code-review --platform claude-code + +# Registry vs registry +skern skill diff code-review code-review-strict --scope user ``` +**Flags:** + +| Flag | Description | +|------|-------------| +| `--scope` | `user` or `project` (omit to search both) | +| `--platform` | Platform to compare against — required when using one argument | + +The output reports per-field diffs (description, version, author, …) plus a body diff flag. In `--json` mode, both bodies are returned in full. + ## `skern skill install` Install one or more skills to a single platform. @@ -195,46 +276,44 @@ Install one or more skills to a single platform. skern skill install ... --platform ``` -Each invocation targets exactly one platform. Agents are expected to specify the platform they are running on; `--platform all` is no longer accepted. To deploy a skill across multiple platforms, loop the call per platform. - -Multiple skill names can be passed in a single call. Each skill's outcome is reported as a separate entry in the `skills` array. A failure on one skill does not abort the batch — the command exits non-zero only when *every* install fails. +Each invocation targets exactly one platform — `--platform all` is not accepted. Multiple skill names can be passed in one call. Each skill's outcome is reported in the `skills[]` array; a failure on one skill does not abort the batch — the command exits non-zero only when *every* install fails. -The response includes a `capacity` block reporting the platform's installed-skill count after the operation, the threshold for that scope, and remaining headroom. Use it to decide whether to evict stale skills before the next install. +The response includes a top-level `capacity` block reporting the platform's installed-skill count after the operation, the threshold for that scope, and remaining headroom. **Flags:** -| Flag | Description | -|------|-------------| -| `--platform` | One of: `claude-code`, `codex-cli`, `opencode`, `cursor`, `gemini-cli`, `github-copilot`, `windsurf`, `continue` (required) | -| `--scope` | `user` or `project` | -| `--force` | Overwrite existing installation | -| `--enforce-budget` | Refuse the operation if it would push the platform's installed-skill count past the per-scope threshold | +| Flag | Default | Description | +|------|---------|-------------| +| `--platform` | — *(required)* | One of: `claude-code`, `codex-cli`, `opencode`, `cursor`, `gemini-cli`, `github-copilot`, `windsurf`, `continue` | +| `--scope` | `user` | `user` or `project` | +| `--force` | `false` | Overwrite existing installation | +| `--enforce-budget` | `false` | Refuse the operation if it would push the platform's installed-skill count past the per-scope threshold | ## `skern skill uninstall` -Remove one or more skills from a platform. +Remove one or more skills from a platform. Mirrors `install` semantics: one platform per call, multiple skills allowed, partial failures reported per-skill, post-op `capacity` block in the response. The registry copy is **not** affected — use `skern skill remove` for that. ```sh skern skill uninstall ... --platform ``` -Mirrors `install` semantics: one platform per call, multiple skills allowed, partial failures are reported per-skill, and the response includes a post-op `capacity` block. - **Flags:** | Flag | Description | |------|-------------| -| `--platform` | One of: `claude-code`, `codex-cli`, `opencode`, `cursor`, `gemini-cli`, `github-copilot`, `windsurf`, `continue` (required) | +| `--platform` | Required. Same enumeration as `install`. | | `--scope` | `user` or `project` | ## `skern platform list` -List all detected platforms. +List all detected platforms, the directories they install to, and whether each was detected on the current host. ```sh skern platform list ``` +Detection is per-platform: each adapter checks its own user-level config dir (`~/.claude`, `~/.cursor`, `~/.gemini`, `~/.copilot`, `~/.codex`, …) so platforms that share `.agents/skills/` as a project directory are still distinguished correctly. + ## `skern platform status` Show a matrix of skills and their installation status across platforms. @@ -255,7 +334,7 @@ skern completion fish ## `skern version` -Print version, commit, and build date. +Print version, commit, and build date. Falls back to `runtime/debug.ReadBuildInfo` when ldflags aren't injected (e.g. binaries built via `go install`). ```sh skern version diff --git a/docs/reference/index.md b/docs/reference/index.md index 0d8bf50..f2d52fe 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,28 +1,29 @@ # CLI Reference -Skern provides a set of commands for managing agent skills across platforms. All commands support `--json` for machine-readable output and `--quiet` for silent operation. +Skern provides a set of commands for managing agent skills across platforms. Every command supports `--json` for machine-readable output and `--quiet` for silent operation. -## Command Groups - -### [Commands](/reference/commands) +## Pages -Full reference for all CLI commands including flags and usage examples. +- [**Commands**](/reference/commands) — full reference for every command including flags and usage examples. +- [**Validation**](/reference/validation) — rules enforced by `skern skill validate` and during skill creation. +- [**Overlap Detection**](/reference/overlap-detection) — fuzzy matching, similarity scoring, and capacity thresholds. -### [Validation](/reference/validation) +## Command Groups -Validation rules enforced by `skern skill validate` and during skill creation. +`skern skill --help` splits subcommands into two groups: -### [Overlap Detection](/reference/overlap-detection) +- **Registry commands** — manage skills in skern itself (`create`, `import`, `edit`, `remove`, `list`, `show`, `search`, `validate`, `version`, `diff`, `recommend`). +- **Platform commands** — deploy registered skills to a platform (`install`, `uninstall`). -How fuzzy matching and similarity scoring prevent skill duplication. +The registry holds the canonical skill. Install copies the skill into a platform's directory; uninstall removes the platform copy without touching the registry; remove deletes the skill from the registry entirely. ## Global Flags | Flag | Description | |------|-------------| | `--json` | Output in JSON format | -| `--quiet` | Suppress non-error output | -| `--scope user\|project` | Target user-level or project-level registry | +| `--quiet` | Suppress non-essential output | +| `--scope user\|project\|all` | Target user-level or project-level registry (most commands) | ## Exit Codes @@ -30,4 +31,4 @@ How fuzzy matching and similarity scoring prevent skill duplication. |------|---------| | 0 | Success | | 1 | Error | -| 2 | Validation failure | +| 2 | Validation failure (`skern skill validate` errors, name validation failures, etc.) | diff --git a/docs/reference/overlap-detection.md b/docs/reference/overlap-detection.md index fe35b98..a751c20 100644 --- a/docs/reference/overlap-detection.md +++ b/docs/reference/overlap-detection.md @@ -1,44 +1,68 @@ -# Overlap Detection +# Overlap Detection & Capacity -When creating a skill, skern checks existing skills for similarity to prevent duplication. This runs automatically during `skern skill create` and during `skern skill list`. +When creating a skill, skern checks existing skills for similarity to prevent duplication. The same scoring runs during `skern skill list` (pairwise) and `skern skill import`. Capacity thresholds are reported on every install/uninstall to help agents size their working set. ## Scoring Methods ### Fuzzy Name Matching -Uses Levenshtein distance with prefix and suffix bonuses to compare skill names. This catches near-identical names like `code-review` and `code-reveiw`. +Levenshtein distance with prefix and suffix bonuses. Catches near-identical names like `code-review` and `code-reveiw`. ### Description Similarity -Keyword overlap scoring using Jaccard similarity between skill descriptions. This identifies skills that serve the same purpose even if named differently. +Keyword overlap (Jaccard similarity) between descriptions. Identifies skills that serve the same purpose even when named differently. ### Tools Overlap -Shared `allowed-tools` entries between skills contribute to the overall similarity score. +Shared `allowed-tools` entries between two skills contribute to the overall score. ## Thresholds | Score | Behavior | |-------|----------| | < 0.6 | Proceed normally | -| >= 0.6 | Warn — show similar skills, continue | -| >= 0.9 | Block — require `--force` to override | +| ≥ 0.6 | **Warn** — show similar skills, continue | +| ≥ 0.9 | **Block** — require `--force` to override | ## Skill Count Warnings -Warnings are triggered when registries grow beyond recommended sizes: +The registry warns when it grows past recommended sizes: -- **Project scope** — warns at > 20 skills -- **User scope** — warns at > 50 skills +- **Project scope** (`.skern/skills/`) — warns at >= 20 skills +- **User scope** (`~/.skern/skills/`) — warns at >= 50 skills + +These are soft limits — skern keeps working, but encourages cleanup. + +## Per-Platform Capacity + +Every `skern skill install` and `skern skill uninstall` response carries a `capacity` block: + +```json +{ + "capacity": { + "platform": "claude-code", + "scope": "user", + "installed": 18, + "threshold": 50, + "headroom": 32, + "over_budget": false + } +} +``` + +Thresholds match the registry: 20 for project scope, 50 for user scope. They are computed against the **platform's** installed-skills directory — when several adapters share `.agents/skills/` as a project directory, both adapters see the same count. + +`--enforce-budget` on `skill install` makes the operation refuse to proceed when the resulting count would exceed the threshold. Off by default, so agents must explicitly opt in. ## During `skill list` -`skern skill list` runs pairwise overlap detection across all listed skills and appends a "Potential duplicates" section when matches are found (score >= 0.6). In `--json` mode, these appear in the `duplicates` array. +`skern skill list` runs pairwise overlap detection across all listed skills and appends a "Potential duplicates" section when matches are found (score ≥ 0.6). In `--json` mode they appear in the `duplicates` array. Use `--with-platforms` to also see where each skill is currently installed. ## Overriding -Use the `--force` flag to bypass overlap blocking during skill creation: +Use `--force` to bypass the overlap block during creation or import: ```sh -skern skill create my-skill --description "..." --force +skern skill create my-skill --description "Use when …" --force +skern skill import https://github.com/owner/repo/tree/main/skill --force ``` diff --git a/docs/reference/validation.md b/docs/reference/validation.md index cd3ead0..5f2446b 100644 --- a/docs/reference/validation.md +++ b/docs/reference/validation.md @@ -1,60 +1,74 @@ # Validation -`skern skill validate ` checks skills against the [Agent Skills](https://agentskills.io) specification. Validation also runs automatically during `skern skill create`, issuing warnings for any issues. +`skern skill validate ` checks skills against the [Agent Skills](https://agentskills.io) specification. Validation also runs automatically during `skern skill create` (warnings only — never blocks creation). -## Rules +## Severity -### Name Format +Validation reports three severities: + +| Severity | Prefix (text) | JSON `severity` | Effect | +|----------|---------------|-----------------|--------| +| **Error** | `✗` | `"error"` | `valid: false`, exit code `2` | +| **Warning** | `!` | `"warning"` | Reported, does not affect validity | +| **Hint** | `~` | `"hint"` | Stylistic suggestion only | + +The summary line counts each separately, e.g. `Skill "x" has 1 error(s), 0 warning(s), 2 hint(s)`. -Skill names must match the pattern `[a-z0-9]+(-[a-z0-9]+)*` and be between 1 and 64 characters. +## Errors + +### Name Format -Valid examples: `code-review`, `lint-fix`, `deploy` +Skill names must match `[a-z0-9]+(-[a-z0-9]+)*` and be 1–64 characters. -Invalid examples: `Code_Review`, `my skill`, `a-very-long-skill-name-that-exceeds-the-sixty-four-character-maximum-limit` +Valid: `code-review`, `lint-fix`, `deploy`. Invalid: `Code_Review`, `my skill`. ### Description -- Required — must not be empty -- Maximum 1024 characters +Required, non-empty, max 1024 characters. ### Body -The `SKILL.md` file must have non-empty body content after the YAML frontmatter. +The `SKILL.md` body (everything after the YAML frontmatter) must not be empty. ### Allowed Tools -If `allowed-tools` is specified in the frontmatter, no entries may be empty strings. +If `allowed-tools` is set, no entry may be empty. -### Metadata +### Author Type -- **Author type** — must be `human` or `agent` -- **Version** — should follow [semantic versioning](https://semver.org) (e.g., `1.0.0`) +`metadata.author.type` must be `human` or `agent` if set. -### Folder Integrity +### Version + +`metadata.version` must be a valid semver string (`MAJOR.MINOR.PATCH`). -When a skill body references files (via backtick-enclosed paths like `` `scripts/run.py` `` or markdown links like `[script](scripts/run.py)`), validation checks that those files exist in the skill directory. Missing references produce **warnings**, not errors — the skill remains valid since references may be aspirational or provided at runtime. +## Warnings -## Stylistic Hints +### Folder Integrity -In addition to errors and warnings, validation reports **hints** — stylistic suggestions that do not affect validity. Hints use a `~` prefix in text output and appear in the `issues` array with `severity: "hint"` in JSON mode. +When the body references files (backtick-enclosed paths like `` `scripts/run.py` `` or markdown links like `[script](scripts/run.py)`), validation checks that those files exist in the skill directory. Missing references produce **warnings**, not errors — references may be aspirational or provided at runtime. -Current hint checks: +Inline code spans and URLs are excluded from this check (no false positives from `` `--flag` `` or `https://…`). -| Check | Trigger | -|-------|---------| -| Short body | Body has fewer than 20 words | -| Vague description | Description has fewer than 3 words | -| No step markers | Body lacks bullet points, numbered lists, or heading markers | +## Hints -Hints are counted separately in the validation summary (e.g., `1 error, 0 warnings, 2 hints`). +Stylistic suggestions adapted from [writing-skills](/writing-skills). They never block creation or validation. + +| Hint | Trigger | +|------|---------| +| Body too short | Body has fewer than 20 words | +| Description too vague | Description has fewer than 3 words | +| Missing trigger prefix | Description doesn't start with "Use when", "Use for", "Use to", "Trigger when", or "Apply when" | +| No step markers | Body lacks bullet points, numbered lists, or "step" markers | +| Missing recommended sections | Body is missing one or more of `When to Use`, `Core Pattern`, `Quick Reference`, `Common Mistakes` | ## Parse Warnings -When `skern skill list` encounters a skill directory that cannot be parsed (e.g., malformed YAML frontmatter), it reports a **parse warning** instead of silently skipping the entry. In text mode these appear as `WARNING:` lines; in `--json` mode they appear in the `parse_warnings` array. +When `skern skill list` encounters a skill directory that cannot be parsed (e.g. malformed YAML frontmatter), it reports a **parse warning** instead of silently skipping the entry. In text mode these appear as `WARNING:` lines; in `--json` mode they populate the `parse_warnings` array. ## Exit Codes | Code | Meaning | |------|---------| -| 0 | Skill is valid | -| 2 | Validation failure | +| 0 | Skill is valid (warnings/hints OK) | +| 2 | Validation failure — at least one error |