diff --git a/AGENTS.md b/AGENTS.md index 6f4bc12..b972dc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -227,7 +227,7 @@ Names must match `^[a-z0-9]+(-[a-z0-9]+)*$` and be 1-64 characters. ## Current Status -All milestones (M0–M5) are complete. The first public release (v0.0.1) has shipped. +All milestones (M0–M5) are complete. The first public release (v0.0.1) has shipped. Recent additions include `skill edit` (metadata + body editing with `modified-by` tracking), skill tags/categories, `--force` flag for install, parse warnings in `skill list`, and stylistic lint hints in `skill validate`. ### Future Roadmap @@ -238,7 +238,6 @@ These items are tracked as GitHub issues: - Skill versioning (semver in frontmatter, upgrade detection) - Community skill catalog integration - Remote catalog search in `skern skill search` -- `skern skill update` with `--author` flag appending to `modified-by` list - Skill dependency resolution - WASI/Docker execution backends diff --git a/docs/concepts/skill-format.md b/docs/concepts/skill-format.md index a3a825f..0c5a3a3 100644 --- a/docs/concepts/skill-format.md +++ b/docs/concepts/skill-format.md @@ -8,6 +8,9 @@ Skills follow the [Agent Skills](https://agentskills.io) open standard. Each ski --- name: code-review description: Review PRs for style and correctness +tags: + - review + - quality version: 1.0.0 author: name: Jane Doe @@ -36,6 +39,7 @@ Review pull requests for: | `author.name` | No | Author name | | `author.type` | No | `human` or `agent` | | `author.platform` | No | Platform name (e.g., `claude-code`) | +| `tags` | No | List of classification tags | | `allowed-tools` | No | List of tools the skill may use | | `modified-by` | No | Modification history entries | diff --git a/docs/guide/installation.md b/docs/guide/installation.md index b3488b3..a9f0f54 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -14,7 +14,7 @@ SKERN_VERSION=v0.0.1 curl -fsSL https://raw.githubusercontent.com/devrimcavusogl ## Go Install -Requires Go 1.23+. +Requires Go 1.25+. ```sh go install github.com/devrimcavusoglu/skern/cmd/skern@latest diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 600ec85..77cfbb7 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -5,6 +5,7 @@ ``` skern init # Initialize .skern/ in current project skern skill create # Scaffold a new skill +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 list [--scope user|project|all] # List skills in registry @@ -43,19 +44,51 @@ skern skill create [flags] | `--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 ` | Use file as skill body | Overlap detection runs automatically during creation. See [Overlap Detection](/reference/overlap-detection) for details. +## `skern skill edit` + +Edit a skill's metadata fields or open the body in an editor. + +```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`). + +**Flags:** + +| Flag | Description | +|------|-------------| +| `--scope` | `user` or `project` | +| `--description` | New description | +| `--author` | New author name | +| `--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-type` | `human` or `agent` | +| `--modified-by-platform` | Platform name for modifier | + ## `skern skill search` Search skills by name or description. ```sh -skern skill search +skern skill search [flags] ``` +**Flags:** + +| Flag | Description | +|------|-------------| +| `--tag` | Filter results to skills with this tag | + ## `skern skill recommend` Get recommendations on whether to reuse, extend, or create a skill. @@ -77,11 +110,20 @@ skern skill recommend [flags] List all skills in the registry. ```sh -skern skill list [--scope user|project|all] +skern skill list [--scope user|project|all] [flags] ``` +**Flags:** + +| Flag | Description | +|------|-------------| +| `--scope` | `user`, `project`, or `all` | +| `--tag` | Filter results to skills with this tag | + 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. +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 show` Display full details for a skill, including author provenance and modification history. @@ -122,6 +164,7 @@ skern skill install --platform |------|-------------| | `--platform` | `claude-code`, `codex-cli`, `opencode`, or `all` (required) | | `--scope` | `user` or `project` | +| `--force` | Overwrite existing installation | ## `skern skill uninstall` diff --git a/docs/reference/validation.md b/docs/reference/validation.md index 626cd4c..cd3ead0 100644 --- a/docs/reference/validation.md +++ b/docs/reference/validation.md @@ -34,6 +34,24 @@ If `allowed-tools` is specified in the frontmatter, no entries may be empty stri 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. +## Stylistic Hints + +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. + +Current hint checks: + +| 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 are counted separately in the validation summary (e.g., `1 error, 0 warnings, 2 hints`). + +## 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. + ## Exit Codes | Code | Meaning |