From b0ef05d222facdc7e9414a271e2477fb34eddeac Mon Sep 17 00:00:00 2001 From: devrimcavusoglu Date: Sat, 7 Mar 2026 13:52:03 +0300 Subject: [PATCH 1/2] Update docs to reflect recent feature additions - Add skill edit command section to commands reference - Document --tags on create, --tag filter on list/search, --force on install - Add tags field to skill format spec (frontmatter table + example) - Document stylistic lint hints and parse warnings in validation reference - Fix Go version requirement from 1.23+ to 1.25+ - Remove completed skill update item from AGENTS.md roadmap Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 3 +-- docs/concepts/skill-format.md | 4 +++ docs/guide/installation.md | 2 +- docs/reference/commands.md | 46 +++++++++++++++++++++++++++++++++-- docs/reference/validation.md | 18 ++++++++++++++ 5 files changed, 68 insertions(+), 5 deletions(-) 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..6fab23d 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,50 @@ 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 | | `--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 +109,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 +163,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 | From a26a9f832f6c0b81ad35f0dacb2cf2f5bf8f45f3 Mon Sep 17 00:00:00 2001 From: devrimcavusoglu Date: Sat, 7 Mar 2026 14:08:07 +0300 Subject: [PATCH 2/2] Add missing --scope flag to skill create docs Co-Authored-By: Claude Opus 4.6 --- docs/reference/commands.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 6fab23d..77cfbb7 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -45,6 +45,7 @@ skern skill create [flags] | `--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 |