From 93860714f12be1a3130152fbd2edf3c26f3c69b8 Mon Sep 17 00:00:00 2001 From: Goon Date: Thu, 12 Mar 2026 18:35:35 +0700 Subject: [PATCH] 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 | 39 +++--- .../references/distribution-guide.md | 126 +++++++++--------- .../references/eval-infrastructure-guide.md | 20 +-- .../references/script-quality-criteria.md | 37 ++--- .../skill-anatomy-and-requirements.md | 27 ++-- .../references/skill-creation-workflow.md | 33 +++-- .../structure-organization-criteria.md | 68 +++++----- .../references/testing-and-iteration.md | 6 +- .../references/troubleshooting-guide.md | 2 +- .../references/validation-checklist.md | 6 +- .../references/yaml-frontmatter-reference.md | 81 +++++------ skills/skill-creator/scripts/init_skill.py | 26 ++-- 12 files changed, 240 insertions(+), 231 deletions(-) diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md index 0eb6f361..eeb842d4 100644 --- a/skills/skill-creator/SKILL.md +++ b/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//`. +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/")` to register in system database +8. **Publish** — `publish_skill(path: "~/.goclaw/skills-store/")` to register in system database 9. **Package** (optional) — `scripts/package_skill.py ` 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///` (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 `, `npm install `). -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 `, `npm install -g `). +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` diff --git a/skills/skill-creator/references/distribution-guide.md b/skills/skill-creator/references/distribution-guide.md index c11c4940..febbdde4 100644 --- a/skills/skill-creator/references/distribution-guide.md +++ b/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/") ``` -## Packaging for Distribution +- Copies files to managed store: `~/.goclaw/skills-store/// (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 -scripts/package_skill.py ./dist # custom output dir +scripts/package_skill.py ~/.goclaw/skills-store/ +# → creates .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 + npm install -g + ``` +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/` → 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 diff --git a/skills/skill-creator/references/eval-infrastructure-guide.md b/skills/skill-creator/references/eval-infrastructure-guide.md index f13ac5c1..a4cbb8f2 100644 --- a/skills/skill-creator/references/eval-infrastructure-guide.md +++ b/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 ` 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 diff --git a/skills/skill-creator/references/script-quality-criteria.md b/skills/skill-creator/references/script-quality-criteria.md index 9ce1be11..ee2b47bf 100644 --- a/skills/skill-creator/references/script-quality-criteria.md +++ b/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//.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 # installs to PIP_TARGET, persists in volume +npm install -g # installs to NPM_CONFIG_PREFIX, persists in volume ``` +Packages installed persist across tool calls within the same container lifecycle. + ## Documentation Requirements ### .env.example diff --git a/skills/skill-creator/references/skill-anatomy-and-requirements.md b/skills/skill-creator/references/skill-anatomy-and-requirements.md index fc7d04a3..afb1704b 100644 --- a/skills/skill-creator/references/skill-anatomy-and-requirements.md +++ b/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 ` or `npm install -g ` (no sudo needed, persists in `/app/data/.runtime/`) - Token-efficient: executed without loading into context See `references/script-quality-criteria.md` for full criteria. diff --git a/skills/skill-creator/references/skill-creation-workflow.md b/skills/skill-creator/references/skill-creation-workflow.md index 61aeae0d..2c275168 100644 --- a/skills/skill-creator/references/skill-creation-workflow.md +++ b/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 --path +scripts/init_skill.py --path ~/.goclaw/skills-store/ ``` -Creates: SKILL.md template, `scripts/`, `references/`, `assets/` with examples. +Creates: `~/.goclaw/skills-store//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/") +``` + +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 # Python packages +npm install -g # Node.js packages +``` + +## Step 9: Package (Optional — for external distribution) ```bash scripts/package_skill.py ``` 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/")` — 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 diff --git a/skills/skill-creator/references/structure-organization-criteria.md b/skills/skill-creator/references/structure-organization-criteria.md index 30a397c9..36f5205a 100644 --- a/skills/skill-creator/references/structure-organization-criteria.md +++ b/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//`. +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 +python3 scripts/skill-creator/scripts/package_skill.py ~/.goclaw/skills-store/ ``` -Checks: -- SKILL.md exists -- Valid frontmatter -- Proper directory structure +Checks: SKILL.md exists, valid frontmatter, proper directory structure. diff --git a/skills/skill-creator/references/testing-and-iteration.md b/skills/skill-creator/references/testing-and-iteration.md index a129f1db..0841acb8 100644 --- a/skills/skill-creator/references/testing-and-iteration.md +++ b/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. diff --git a/skills/skill-creator/references/troubleshooting-guide.md b/skills/skill-creator/references/troubleshooting-guide.md index 01857187..e4cfd537 100644 --- a/skills/skill-creator/references/troubleshooting-guide.md +++ b/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) diff --git a/skills/skill-creator/references/validation-checklist.md b/skills/skill-creator/references/validation-checklist.md index 41b3622c..2470a9ab 100644 --- a/skills/skill-creator/references/validation-checklist.md +++ b/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 ` or `npm install -g ` (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 diff --git a/skills/skill-creator/references/yaml-frontmatter-reference.md b/skills/skill-creator/references/yaml-frontmatter-reference.md index 7ca4a113..92a32bac 100644 --- a/skills/skill-creator/references/yaml-frontmatter-reference.md +++ b/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:** diff --git a/skills/skill-creator/scripts/init_skill.py b/skills/skill-creator/scripts/init_skill.py index 3213c112..47bcc090 100644 --- a/skills/skill-creator/scripts/init_skill.py +++ b/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