Refresh docs site for v0.2.1 (eight platforms, init instructions, skill versioning)

Bring the VitePress site up to date with the v0.2.0 / v0.2.1 surface that has
landed since the last docs refresh:

- Eight platform adapters wherever 3 were listed (index, guide, concepts diagram,
  reference flag enums, platforms index/comparison) and a dedicated page for
  each new adapter (cursor, gemini-cli, github-copilot, windsurf, continue).
- `skern init --instructions` / `--tool-forming-loop` / `--target` /
  `--print-instructions` documented in the quick-start, agent-setup, and command
  reference. Agent-setup now leads with `init --instructions` instead of the
  manual `echo … >> AGENTS.md` recipe.
- Reference reorganized: registry vs. platform command groups, full pages for
  `skill import`, `skill version`, `skill diff`, capacity reporting on
  install/uninstall, `--enforce-budget`, `--with-platforms`, batch
  install/uninstall.
- Validation page split into errors / warnings / hints with the trigger-prefix
  and recommended-section hints.
- Skill format page corrected to the nested `metadata.author` / `metadata.version`
  / `metadata.modified-by` schema and includes the import workflow.
- Installation page covers macOS, Linux, and Windows (PowerShell) one-liners
  plus version pinning, custom install dir, source build, manual install,
  uninstall.
- Contributing/development reflects the declarative platform spec, updated
  Make targets, and the `cli/instructions/` package.
- Sidebar adds the new platform pages and a Writing Skills entry under Guide.

Build verified with `npm run docs:build` (clean).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: devrimcavusoglu

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' },
           ],
         },
       ],

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.

docs/concepts/skill-format.md

@@ -1,99 +1,131 @@
 # 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 <name>` 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
 └── assets/
     └── 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 <name>` to see which files are bundled with a skill, and `skern skill validate <name>` to check that files referenced in the skill body actually exist.
+`skern skill validate <name>` 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 <name>` lists every file bundled with the skill.
 
 ## Creating Skills
 
 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 <dir>` 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 <dir>` 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 `<name>` 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 <url>` 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/<id>
+skern skill import <url> --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 `<name>` 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.

docs/contributing/development.md

@@ -3,49 +3,94 @@
 ## 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`.
 
 ## 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 `#<number>`.
+
+```sh
+gh issue list                              # List open issues
+gh issue create --title "Title" --body ""  # Create a new issue
+gh issue view <number>                     # View issue details
+```
+
+## Branching
+
+Work is organized by milestone using feature branches:
+
+- **Branch naming**: `feature/m<N>-<slug>` (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.