fix(skills): update skill-creator paths and metadata for GoClaw (#168)

Align skill-creator with GoClaw conventions: update skill store paths
to ~/.goclaw/skills-store/, fix author metadata, remove external
Claude Code references, update publish_skill documentation.

skills/skill-creator/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: skill-creator
-description: Create or update Claude skills with eval-driven iteration. Use for new skills, skill scripts, references, benchmark optimization, description optimization, eval testing, extending Claude's capabilities.
+description: Create or update GoClaw agent skills with eval-driven iteration. Use for new skills, skill scripts, references, benchmark optimization, description optimization, eval testing, extending agent capabilities.
 license: Complete terms in LICENSE.txt
-argument-hint: "[skill-name or description]"
 metadata:
-  author: claudekit
+  author: GoClaw
   version: "4.0.0"
 ---
 
@@ -30,7 +29,8 @@ Create effective, eval-driven Claude skills using progressive disclosure and hum
 
 ## Skill Structure
 
-New skills **MUST** be created in CWD: `skills/` directory (workspace root)
+New skills **MUST** be created directly in `~/.goclaw/skills-store/<skill-name>/`.
+After writing SKILL.md and resources, use `publish_skill` to register in the system DB.
 
 ```
 skill-name/
@@ -54,7 +54,7 @@ Follow the process in `references/skill-creation-workflow.md`:
 5. **Write** — Implement resources, write SKILL.md, optimize for benchmarks
 6. **Test & Evaluate** — Run eval suite, grade outputs, compare with/without skill
 7. **Optimize Description** — AI-powered trigger accuracy optimization
-8. **Publish** — `publish_skill(path: "skills/<name>")` to register in system database
+8. **Publish** — `publish_skill(path: "~/.goclaw/skills-store/<name>")` to register in system database
 9. **Package** (optional) — `scripts/package_skill.py <path>` for external distribution
 10. **Iterate** — Generalize from feedback, keep prompts lean
 
@@ -66,7 +66,7 @@ Eval infrastructure for quantitative skill validation:
 3. Draft assertions while runs execute
 4. Grade outputs with grader agent template
 5. Aggregate results: `scripts/aggregate_benchmark.py`
-6. Launch viewer: `scripts/generate_review.py` → interactive HTML review
+6. Launch viewer: `eval-viewer/generate_review.py` → interactive HTML review
 7. Collect human feedback via viewer → `feedback.json`
 
 Details: `references/eval-infrastructure-guide.md`
@@ -132,27 +132,26 @@ Optimization patterns: `references/benchmark-optimization-guide.md`
 | `scripts/aggregate_benchmark.py` | Consolidate runs into summary stats |
 | `scripts/improve_description.py` | AI-powered description optimization |
 | `scripts/run_loop.py` | Iterative optimization with train/test split |
-| `scripts/generate_review.py` | Generate interactive HTML eval viewer |
+| `eval-viewer/generate_review.py` | Generate interactive HTML eval viewer |
 
 ## Publishing to System
 
-After creating and validating a skill, register it in the system database:
+After creating and validating a skill, register it in the GoClaw database:
 
 ```
-publish_skill(path: "skills/my-skill")
+publish_skill(path: "~/.goclaw/skills-store/my-skill")
 ```
 
 This tool:
-- Copies skill files to the managed skills store
-- Registers metadata (name, description, slug) in the database
-- Auto-grants the skill to the creating agent
+- Copies skill files to `~/.goclaw/skills-store/<slug>/<version>/` (Docker: `/app/.goclaw/skills-store/`)
+- Registers metadata (name, slug, description) in the database
 - Scans dependencies and reports any missing ones
-- Generates search embeddings for skill discovery
+- Generates BM25/embedding index for skill discovery
 
-If dependencies are missing, try installing them via `exec` (e.g. `pip install <pkg>`, `npm install <pkg>`).
-If system binaries are missing and you cannot install them, inform the user.
+If dependencies are missing, try installing via `exec` (e.g. `pip3 install <pkg>`, `npm install -g <pkg>`).
+If system binaries are missing and cannot be installed, inform the user.
 
-Re-publishing the same slug updates the existing skill (upsert behavior, increments version).
+Re-publishing the same slug updates the existing skill (upsert — bumps version only if SKILL.md content changes).
 
 ## Validation & Distribution
 
@@ -162,10 +161,4 @@ Re-publishing the same slug updates the existing skill (upsert behavior, increme
 - **Scripts**: `references/script-quality-criteria.md`
 - **Structure**: `references/structure-organization-criteria.md`
 - **Design patterns**: `references/skill-design-patterns.md`
-- **Plugin Marketplaces**: `references/plugin-marketplace-overview.md`
-
-## External References
-
-- [Agent Skills Docs](https://docs.claude.com/en/docs/claude-code/skills.md)
-- [Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md)
-- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md)
+- **Distribution**: `references/distribution-guide.md`

skills/skill-creator/references/distribution-guide.md

@@ -1,79 +1,81 @@
 # Distribution Guide
 
-## Current Distribution Model
+## Distribution Models in GoClaw
 
-### Individual Users
-1. Download skill folder
-2. Zip the folder
-3. Upload to Claude.ai: Settings > Capabilities > Skills
-4. Or place in Claude Code skills directory: `.claude/skills/`
+### 1. Publish to Current Instance (Primary)
 
-### Organization-Level
-- Admins deploy skills workspace-wide
-- Automatic updates, centralized management
+Register skill directly in the running GoClaw instance:
 
-### Via API
-- `/v1/skills` endpoint for managing skills programmatically
-- Add to Messages API via `container.skills` parameter
-- Version control through Claude Console
-- Works with Claude Agent SDK for custom agents
-
-| Use Case | Best Surface |
-|---|---|
-| End users interacting directly | Claude.ai / Claude Code |
-| Manual testing during development | Claude.ai / Claude Code |
-| Applications using skills programmatically | API |
-| Production deployments at scale | API |
-| Automated pipelines and agent systems | API |
-
-## Recommended Approach
-
-### 1. Host on GitHub
-- Public repo for open-source skills
-- Clear README with installation instructions (repo-level, NOT inside skill folder)
-- Example usage and screenshots
-
-### 2. Document in MCP Repo (if applicable)
-- Link to skills from MCP documentation
-- Explain value of using both together
-- Provide quick-start guide
-
-### 3. Create Installation Guide
-
-```markdown
-## Installing the [Service] Skill
-1. Download: `git clone https://github.com/company/skills`
-   Or download ZIP from Releases
-2. Install: Claude.ai > Settings > Skills > Upload skill (zipped)
-3. Enable: Toggle on the skill, ensure MCP server connected
-4. Test: Ask Claude "[trigger phrase from description]"
+```
+publish_skill(path: "~/.goclaw/skills-store/<name>")
 ```
 
-## Packaging for Distribution
+- Copies files to managed store: `~/.goclaw/skills-store/<slug>/<version>/  (Docker: /app/.goclaw/skills-store/)`
+- Registers in `skills` table (`is_system=false`, `visibility='public'`)
+- Scans + reports missing dependencies
+- Auto-increments version only if SKILL.md content (SHA-256) changes
 
-Run packaging script to validate and zip:
+### 2. Upload via Admin UI
+
+Package skill as ZIP, then upload via GoClaw admin dashboard (`/skills` page):
 
 ```bash
-scripts/package_skill.py <path/to/skill-folder>
-scripts/package_skill.py <path/to/skill-folder> ./dist  # custom output dir
+scripts/package_skill.py ~/.goclaw/skills-store/<name>
+# → creates <name>.zip
 ```
 
-Validates: frontmatter, naming, description (<200 chars), structure.
-Creates: `skill-name.zip` with proper directory structure.
+Upload at: **Admin UI → Skills → Upload skill**
 
-## Plugin Marketplaces
+Use case: distributing skills to other GoClaw instances without direct filesystem access.
 
-For marketplace distribution, see:
-- `plugin-marketplace-overview.md` — Concepts and workflow
-- `plugin-marketplace-schema.md` — JSON schema for marketplace.json
-- `plugin-marketplace-sources.md` — Source types (path, GitHub, git)
-- `plugin-marketplace-hosting.md` — Hosting options and auto-updates
-- `plugin-marketplace-troubleshooting.md` — Common issues
+### 3. Bundled Skills (Image-level)
 
-## Positioning Your Skill
+Skills placed in the `skills/` directory of the repo are bundled into the Docker image:
 
-**Focus on outcomes:**
-> "Enables teams to set up complete project workspaces in seconds instead of 30-minute manual setup."
+```
+skills/
+└── my-skill/
+    └── SKILL.md
+```
 
-**Include MCP story (if applicable):**
-> "Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your sprint planning workflow. Together: AI-powered project management."
+Rebuild required: `docker compose up -d --build`
+
+Bundled skills are seeded automatically on gateway startup. They have lowest priority — user-uploaded skills with same slug override them.
+
+Use case: ship default skills with every GoClaw deployment.
+
+## Version Management
+
+GoClaw manages versions automatically via content hash:
+
+| Scenario | Result |
+|----------|--------|
+| First publish | `version = 1` |
+| Re-publish, content unchanged | No-op (version stays) |
+| Re-publish, SKILL.md changed | `version += 1` |
+| Upload same slug via UI | Version bumped, new files copied |
+
+Do NOT manually set `version` in SKILL.md frontmatter — it has no effect on GoClaw's versioning.
+
+## Dependency Handling
+
+After publishing, GoClaw scans for missing Python/Node deps automatically.
+
+If deps are missing (`status = archived`):
+1. View missing deps in Admin UI → Skills → skill row
+2. Click "Install" per-dep, or install manually via exec tool:
+   ```bash
+   pip3 install <pkg>
+   npm install -g <pkg>
+   ```
+3. Skill auto-transitions to `status = active` after install
+
+System packages (apk) require `ENABLE_PYTHON=true` and `doas` available in the image.
+
+## Sharing Skills
+
+To share a skill externally:
+
+1. Package: `scripts/package_skill.py ~/.goclaw/skills-store/<name>` → ZIP file
+2. Share the ZIP — recipient uploads via Admin UI → Skills → Upload
+3. Or contribute to `skills/` directory in the GoClaw repo for bundling

skills/skill-creator/references/eval-infrastructure-guide.md

@@ -112,18 +112,12 @@ Read `feedback.json`, generalize from patterns:
 - Data processing: +50-80% pass rate, -30-50% time
 - Analysis: +30-50% pass rate
 
-## Environment Adaptations
+## GoClaw Eval Context
 
-### Claude Code (Full)
-- Spawn parallel with+without runs
-- Full benchmarking + viewer
-- Description optimization available
+GoClaw agents run via WebSocket RPC. Eval runs execute within the agent loop (think→act→observe).
 
-### Claude.ai (No subagents)
-- Run tests sequentially
-- Skip baseline runs
-- Skip quantitative benchmarking
-
-### Cowork (No browser)
-- Use `--static <output_path>` for standalone HTML
-- Download feedback.json from viewer
+- Spawn parallel eval runs as subagent tasks (each in its own session)
+- Baseline run: same prompt, skill disabled (`enabled=false` via Admin UI or toggle API)
+- With-skill run: skill enabled (`enabled=true`)
+- Compare outputs via grader agent template
+- Use `eval-viewer/generate_review.py` to generate HTML review locally

skills/skill-creator/references/script-quality-criteria.md

@@ -29,34 +29,25 @@ npm test
 
 Tests must pass. No skipping failed tests.
 
-## Environment Variables
+## Runtime Environment (GoClaw)
 
-Respect hierarchy (first found wins):
+Scripts run inside the GoClaw container via the `exec` tool. Environment is set by the entrypoint:
 
-1. `process.env` (runtime)
-2. `$HOME/.claude/skills/<skill-name>/.env` (skill-specific)
-3. `$HOME/.claude/skills/.env` (shared skills)
-4. `$HOME/.claude/.env` (global)
-5. `./.claude/skills/${SKILL}/.env` (cwd)
-6. `./.claude/skills/.env` (cwd)
-7. `./.claude/.env` (cwd)
+| Variable | Value | Purpose |
+|----------|-------|---------|
+| `PYTHONPATH` | `/app/.goclaw/data/.runtime/pip` | Python runtime packages |
+| `PIP_TARGET` | `/app/.goclaw/data/.runtime/pip` | pip install target |
+| `NPM_CONFIG_PREFIX` | `/app/.goclaw/data/.runtime/npm-global` | npm global install dir |
+| `NODE_PATH` | `/usr/local/lib/node_modules:...` | Node module resolution |
 
-**Implementation pattern (Python):**
-
-```python
-from dotenv import load_dotenv
-import os
-
-# Load in reverse order (last loaded wins if not set)
-load_dotenv('$HOME/.claude/.env')
-load_dotenv('$HOME/.claude/skills/.env')
-load_dotenv('$HOME/.claude/skills/my-skill/.env')
-load_dotenv('./.claude/skills/my-skill/.env')
-load_dotenv('./.claude/skills/.env')
-load_dotenv('./.claude/.env')
-# process.env already takes precedence
+**Installing packages at runtime (no sudo needed):**
+```bash
+pip3 install <package>        # installs to PIP_TARGET, persists in volume
+npm install -g <package>      # installs to NPM_CONFIG_PREFIX, persists in volume
 ```
 
+Packages installed persist across tool calls within the same container lifecycle.
+
 ## Documentation Requirements
 
 ### .env.example

skills/skill-creator/references/skill-anatomy-and-requirements.md

@@ -3,8 +3,8 @@
 ## Directory Structure
 
 ```
-.claude/skills/
-└── skill-name/
+~/.goclaw/skills-store/
+└── skill-name/           ← directory name IS the slug (unique DB identifier)
     ├── SKILL.md          (required, <300 lines)
     │   ├── YAML frontmatter (name, description required)
     │   └── Markdown instructions
@@ -26,24 +26,31 @@
 
 ## SKILL.md Frontmatter
 
+Per [Agent Skills specification](https://agentskills.io/specification.md):
+
 ```yaml
 ---
-name: kebab-case-name  # optional namespace: ck:kebab-case-name
-description: Under 200 chars, specific triggers and use cases
-license: Optional
-version: Optional
+name: skill-name          # required — must be kebab-case, match directory name
+description: Under 1024 chars, specific triggers and use cases  # required
+license: Optional         # optional
+compatibility: Optional   # optional, environment requirements
+metadata:                 # optional, arbitrary key-value pairs
+  author: Author Name
+  version: "1.0"
+allowed-tools: "Bash(python3:*) Bash(node:*)"  # optional, experimental
 ---
 ```
 
+**Key:** `name` must be lowercase, kebab-case, and **match the directory name exactly** — GoClaw uses the directory name as the slug (DB key). Changing directory name = new skill.
+
 **Metadata quality** determines auto-activation. See `references/metadata-quality-criteria.md`.
 
 ## Scripts (`scripts/`)
 
 - Deterministic code for repeated tasks
-- **Prefer:** Python or Node.js (Windows-compatible)
-- **Avoid:** Bash scripts
-- **Required:** Tests that pass, `.env.example`, `requirements.txt`/`package.json`
-- **Env hierarchy:** `process.env` > skill `.env` > shared `.env` > global `.env`
+- **Prefer:** Python or Node.js (available in GoClaw runtime)
+- **Avoid:** Bash scripts for complex logic
+- Runtime packages: use `pip3 install <pkg>` or `npm install -g <pkg>` (no sudo needed, persists in `/app/data/.runtime/`)
 - Token-efficient: executed without loading into context
 
 See `references/script-quality-criteria.md` for full criteria.

skills/skill-creator/references/skill-creation-workflow.md

@@ -48,10 +48,10 @@ Scripts MUST: respect `.env` hierarchy, have tests, pass all tests.
 For new skills, run init script:
 
 ```bash
-scripts/init_skill.py <skill-name> --path <output-directory>
+scripts/init_skill.py <skill-name> --path ~/.goclaw/skills-store/
 ```
 
-Creates: SKILL.md template, `scripts/`, `references/`, `assets/` with examples.
+Creates: `~/.goclaw/skills-store/<skill-name>/SKILL.md` template, `scripts/`, `references/`, `assets/` with examples.
 Skip if skill already exists (go to Step 5).
 
 ## Step 5: Write the Skill
@@ -130,22 +130,39 @@ Combat undertriggering with automated optimization:
 - **Single-pass:** `scripts/improve_description.py` — one iteration
 - **Iterative loop:** `scripts/run_loop.py` — train/test split, convergence detection
 
-## Step 8: Package & Validate
+## Step 8: Publish to GoClaw
+
+Register the skill in the GoClaw database:
+
+```
+publish_skill(path: "~/.goclaw/skills-store/<name>")
+```
+
+This copies skill files to the managed store, registers metadata in DB, scans deps,
+and generates search embeddings. Re-publishing same slug → upsert (version bumped only if content changed).
+
+If deps are missing after publish, install via exec:
+```bash
+pip3 install <pkg>        # Python packages
+npm install -g <pkg>      # Node.js packages
+```
+
+## Step 9: Package (Optional — for external distribution)
 
 ```bash
 scripts/package_skill.py <path/to/skill-folder>
 ```
 
 Validates: frontmatter, naming, description, structure.
+Creates: `skill-name.zip` for uploading to other GoClaw instances via the admin UI.
 Fix all errors, re-run until clean.
 
-## Step 9: Iterate
+## Step 10: Iterate
 
 1. Read `feedback.json` from viewer
 2. Generalize from feedback — don't overfit to test examples
 3. Keep prompts lean — remove ineffective instructions
 4. Update SKILL.md or resources
-5. Re-test (return to Step 6)
-6. Scale test set to 5-10 cases for production skills
-
-**Benchmark iteration:** Run `skillmark` CLI, review per-concept accuracy, fix gaps.
+5. Re-publish: `publish_skill(path: "~/.goclaw/skills-store/<name>")` — DB version auto-increments only if content changed
+6. Re-test (return to Step 6)
+7. Scale test set to 5-10 cases for production skills

skills/skill-creator/references/structure-organization-criteria.md

@@ -4,47 +4,50 @@ Proper structure enables discovery and maintainability.
 
 ## Required Directory Layout
 
+Skills are created directly in `~/.goclaw/skills-store/<skill-name>/`.
+After writing SKILL.md, use `publish_skill` to register in the DB (version managed by GoClaw).
+
 ```
-.claude/skills/
-└── skill-name/
-    ├── SKILL.md          # Required, uppercase
-    ├── scripts/          # Optional: executable code
-    ├── references/       # Optional: documentation
-    └── assets/           # Optional: output resources
+~/.goclaw/skills-store/
+└── skill-name/          ← directory name = slug (DB key)
+    ├── SKILL.md         # Required, exact uppercase filename
+    ├── scripts/         # Optional: executable code
+    ├── references/      # Optional: documentation
+    └── assets/          # Optional: output resources
 ```
 
 ## SKILL.md Requirements
 
-**File name:** Exactly `SKILL.md` (uppercase)
+**File name:** Exactly `SKILL.md` (case-sensitive)
 
-**YAML Frontmatter:** Required at top
+**YAML Frontmatter** per [Agent Skills spec](https://agentskills.io/specification.md):
 
 ```yaml
 ---
-name: skill-name  # optional namespace: ck:skill-name
-description: Under 200 chars, specific triggers
+name: skill-name           # required, kebab-case, must match directory name
+description: Under 1024 chars, specific triggers
 license: Optional
-version: Optional
+metadata:
+  author: GoClaw
+  version: "1.0"
 ---
 ```
 
 ## Resource Directories
 
 ### scripts/
-Executable code for deterministic tasks.
+Executable code for deterministic tasks. Runs via GoClaw's `exec` tool (no sudo needed).
+Packages installed at runtime persist to `/app/.goclaw/data/.runtime/`.
 
 ```
 scripts/
-├── main_operation.py
-├── helper_utils.py
-├── requirements.txt
-├── .env.example
-└── tests/
-    └── test_main_operation.py
+├── main-operation.py
+├── helper-utils.py
+└── requirements.txt       # document dependencies
 ```
 
 ### references/
-Documentation loaded into context as needed.
+Documentation loaded into context as needed. Keep each file under 300 lines.
 
 ```
 references/
@@ -54,18 +57,17 @@ references/
 ```
 
 ### assets/
-Files used in output, not loaded into context.
+Files used in output, NOT loaded into context.
 
 ```
 assets/
 ├── templates/
-├── images/
 └── boilerplate/
 ```
 
 ## File Naming
 
-**Format:** kebab-case, descriptive
+**Format:** kebab-case, descriptive (self-documenting for LLM Grep/Glob)
 
 **Good:**
 - `api-endpoints-authentication.md`
@@ -73,24 +75,23 @@ assets/
 - `rotate-pdf-script.py`
 
 **Bad:**
-- `docs.md` - not descriptive
-- `apiEndpoints.md` - wrong case
-- `1.md` - meaningless
+- `docs.md` — not descriptive
+- `apiEndpoints.md` — wrong case
+- `1.md` — meaningless
 
 ## Cleanup
 
 After initialization, delete unused example files:
 
 ```bash
-# Remove if not needed
-rm -rf scripts/example_script.py
-rm -rf references/example_reference.md
-rm -rf assets/example_asset.txt
+rm -f scripts/example.py
+rm -f references/api_reference.md
+rm -f assets/example_asset.txt
 ```
 
 ## Scope Consolidation
 
-Related topics should be combined into single skill:
+Related topics should be combined into one skill:
 
 **Consolidate:**
 - `cloudflare` + `cloudflare-r2` + `cloudflare-workers` → `devops`
@@ -105,10 +106,7 @@ Related topics should be combined into single skill:
 Run packaging script to check structure:
 
 ```bash
-scripts/package_skill.py <skill-path>
+python3 scripts/skill-creator/scripts/package_skill.py ~/.goclaw/skills-store/<name>
 ```
 
-Checks:
-- SKILL.md exists
-- Valid frontmatter
-- Proper directory structure
+Checks: SKILL.md exists, valid frontmatter, proper directory structure.

skills/skill-creator/references/testing-and-iteration.md

@@ -3,9 +3,9 @@
 ## Testing Approaches
 
 Choose rigor based on skill visibility:
-- **Manual testing** — Run queries in Claude.ai, observe behavior. Fast iteration.
-- **Scripted testing** — Automate test cases in Claude Code for repeatable validation.
-- **Programmatic testing** — Build eval suites via skills API for systematic testing.
+- **Manual testing** — Run queries in GoClaw chat, observe behavior. Fast iteration.
+- **Scripted testing** — Automate test cases via eval suite scripts for repeatable validation.
+- **Programmatic testing** — Build eval suites with `evals/evals.json` for systematic grading.
 
 **Pro tip:** Iterate on a single challenging task until Claude succeeds, then extract the winning approach into the skill. Expand to multiple test cases after.
 

skills/skill-creator/references/troubleshooting-guide.md

@@ -52,7 +52,7 @@
 
 **Symptom:** Skill loads but MCP calls fail.
 
-1. Verify MCP server is connected (Settings > Extensions)
+1. Verify MCP server is configured in the agent's tool config (Admin UI → Agents → Tools)
 2. Check API keys valid and not expired
 3. Test MCP independently: "Use [Service] MCP to fetch my projects"
 4. Verify skill references correct MCP tool names (case-sensitive)

skills/skill-creator/references/validation-checklist.md

@@ -22,9 +22,9 @@ Quick validation before packaging. Run `scripts/package_skill.py` for automated
 
 - [ ] Tests exist and pass
 - [ ] Cross-platform (Node.js/Python preferred)
-- [ ] Env vars: respects hierarchy `process.env` > `$HOME/.claude/skills/${SKILL}/.env` (global) > `$HOME/.claude/skills/.env` (global) > `$HOME/.claude/.env` (global) > `./.claude/skills/${SKILL}/.env` (cwd) > `./.claude/skills/.env` (cwd) > `./.claude/.env` (cwd)
-- [ ] Dependencies documented (requirements.txt, .env.example)
-- [ ] Manually tested with real use cases
+- [ ] Runtime packages installed via `pip3 install <pkg>` or `npm install -g <pkg>` (no sudo, persists in `/app/data/.runtime/`)
+- [ ] Dependencies listed in `references/` or SKILL.md so users know what to install
+- [ ] Manually tested with real use cases inside GoClaw exec tool
 
 ## Quality
 

skills/skill-creator/references/yaml-frontmatter-reference.md

@@ -1,5 +1,7 @@
 # YAML Frontmatter Reference
 
+Per [Agent Skills specification](https://agentskills.io/specification.md).
+
 ## Required Fields
 
 ```yaml
@@ -9,79 +11,80 @@ description: What it does and when to use it. Include specific trigger phrases.
 ---
 ```
 
-## All Optional Fields
+## All Fields
 
 ```yaml
 ---
-name: skill-name
-description: [required - under 200 chars]
-license: MIT                                         # Open-source license
-compatibility: Requires Python 3.10+, network access # 1-500 chars, environment needs
-allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Restrict tool access
-metadata:                                            # Custom key-value pairs
+name: skill-name                                     # required — kebab-case, matches dir name
+description: [required — under 1024 chars]           # required
+license: MIT                                         # optional — license name or file ref
+compatibility: Requires Python 3.10+, network access # optional — 1-500 chars
+metadata:                                            # optional — arbitrary key-value pairs
   author: Company Name
-  version: 1.0.0
-  mcp-server: server-name
+  version: "1.0"
   category: productivity
   tags: [project-management, automation]
-  documentation: https://example.com/docs
-  support: support@example.com
+allowed-tools: "Bash(python3:*) Bash(node:*) Read"  # optional — experimental
 ---
 ```
 
 ## Field Details
 
 ### name (required)
-- Supports either `skill-name` or `namespace:skill-name` (for example `ck:plan`)
-- If namespaced, namespace and skill id both use kebab-case only (no spaces, no capitals)
-- Folder name must match the skill id segment (after `:`)
-- Cannot contain "claude" or "anthropic" (reserved)
+- Must be **1-64 characters**
+- Lowercase letters, digits, hyphens only (`a-z`, `0-9`, `-`)
+- Must not start or end with a hyphen
+- Must not contain consecutive hyphens (`--`)
+- **Must match the parent directory name** exactly
+- GoClaw uses directory name as the DB slug — `name` is also used as display name fallback
 
 ### description (required)
-- Under 200 characters (1024 max per spec, but 200 for this project)
+- **Under 1024 characters** (keep under 200 for concision)
 - Structure: `[What it does] + [When to use it] + [Key capabilities]`
-- Include trigger phrases users would actually say
+- Include trigger phrases users/agents would actually say
 - Mention relevant file types if applicable
-- Use third-person: "This skill should be used when..."
 
 ### license (optional)
-- Common: MIT, Apache-2.0
-- Reference full terms in LICENSE.txt if needed
+- Common: `MIT`, `Apache-2.0`, `Proprietary`
+- Can reference bundled file: `"Proprietary. LICENSE.txt has complete terms"`
 
 ### compatibility (optional)
 - 1-500 characters
-- Environment requirements: intended product, system packages, network access
-
-### allowed-tools (optional)
-- Restricts which tools the skill can use
-- Space-separated tool patterns
+- Describe environment requirements: intended product, system packages, network access
+- Most skills don't need this field
 
 ### metadata (optional)
-- Any custom key-value pairs
-- Suggested: author, version, mcp-server, category, tags
+- Arbitrary key-value map for additional properties
+- Suggested keys: `author`, `version`, `category`
 
-## Security Restrictions
+### allowed-tools (optional, experimental)
+- Space-delimited tool patterns pre-approved for this skill
+- Support varies between agent implementations
 
-**Forbidden in frontmatter:**
-- XML angle brackets (`< >`) — frontmatter appears in system prompt, could inject instructions
-- Skills named with "claude" or "anthropic" prefix (reserved)
+## GoClaw Behavior
 
-**Allowed:**
-- Standard YAML types (strings, numbers, booleans, lists, objects)
-- Custom metadata fields
-- Long descriptions up to 1024 characters (project standard: 200)
+GoClaw reads only `name` and `description` from frontmatter (the `Metadata` struct).
+All other fields are stored as raw `frontmatter JSONB` in the DB for display purposes.
+
+The **slug** (DB key) is always derived from the **directory name**, not from frontmatter:
+```
+skills/read-pdf/SKILL.md  →  slug = "read-pdf"
+```
+
+Renaming the directory creates a new skill entry. Same directory = upsert existing.
 
 ## Description Examples
 
 **Good — specific with triggers:**
 ```yaml
-description: Analyzes Figma design files and generates developer handoff docs.
-  Use when user uploads .fig files or asks for "design specs" or "design-to-code".
+description: Extracts text and tables from PDF files, fills PDF forms, and merges
+  multiple PDFs. Use when working with PDF documents or when user mentions PDFs,
+  forms, or document extraction.
 ```
 
 ```yaml
-description: Manages Linear project workflows including sprint planning and
-  task creation. Use when user mentions "sprint", "Linear tasks", or "create tickets".
+description: Create, edit, and read Word .docx files. Triggers: 'Word doc',
+  '.docx', reports, memos, letters, tracked changes, table of contents.
 ```
 
 **Bad — vague or missing triggers:**

skills/skill-creator/scripts/init_skill.py

@@ -22,8 +22,11 @@ configure_utf8_console()
 
 
 SKILL_TEMPLATE = """---
-name: {skill_name}
+name: {skill_slug}
 description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+metadata:
+  author: GoClaw
+  version: "1.0"
 ---
 
 # {skill_title}
@@ -275,15 +278,16 @@ def init_skill(skill_name, path):
         return None
 
     # Create SKILL.md from template
-    skill_title = title_case_skill_name(skill_slug)
-    skill_content = SKILL_TEMPLATE.format(
-        skill_name=full_name,
-        skill_title=skill_title
-    )
+    skill_content = SKILL_TEMPLATE
 
     skill_md_path = skill_dir / 'SKILL.md'
     try:
-        write_text_utf8(skill_md_path, skill_content)
+        skill_title = title_case_skill_name(skill_slug)
+        skill_content_rendered = skill_content.format(
+            skill_slug=skill_slug,
+            skill_title=skill_title,
+        )
+        write_text_utf8(skill_md_path, skill_content_rendered)
         print("✅ Created SKILL.md")
     except Exception as e:
         print(f"❌ Error creating SKILL.md: {e}")
@@ -317,11 +321,11 @@ def init_skill(skill_name, path):
         return None
 
     # Print next steps
-    print(f"\n✅ Skill '{full_name}' initialized successfully at {skill_dir}")
+    print(f"\n✅ Skill '{full_name}' initialized at {skill_dir}")
     print("\nNext steps:")
-    print("1. Edit SKILL.md to complete the TODO items and update the description")
-    print("2. Customize or delete the example files in scripts/, references/, and assets/")
-    print("3. Run the validator when ready to check the skill structure")
+    print("1. Edit SKILL.md — fill in description, update metadata.author/version")
+    print("2. Customize or delete example files in scripts/, references/, assets/")
+    print("3. Publish: publish_skill(path: \"skills/" + skill_slug + "\")")
 
     return skill_dir