Update docs for recent feature additions

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
 

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 |
 

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

docs/reference/commands.md

@@ -5,6 +5,7 @@
 ```
 skern init                                    # Initialize .skern/ in current project
 skern skill create <name>                     # Scaffold a new skill
+skern skill edit <name>                       # Edit skill metadata or body
 skern skill search <query>                    # Search skills by name/description
 skern skill recommend <query>                 # Recommend: reuse, extend, or create
 skern skill list [--scope user|project|all]   # List skills in registry
@@ -43,19 +44,51 @@ skern skill create <name> [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 <path>` | 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 <name> [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 <query>
+skern skill search <query> [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 <query> [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 <name> --platform <platform>
 |------|-------------|
 | `--platform` | `claude-code`, `codex-cli`, `opencode`, or `all` (required) |
 | `--scope` | `user` or `project` |
+| `--force` | Overwrite existing installation |
 
 ## `skern skill uninstall`
 

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 |