From 3a85632df01ecc0fa600244af28f64316b975c5b Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 22 Jun 2026 19:35:10 +0000 Subject: [PATCH] refactor(kyberforge): make skill-write and skill-audit self-contained with shared resources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move validate.sh ownership to skill-audit/scripts/ — it is the canonical structural validator; skill-write now delegates Step 5 to /skill-audit - Add skill-write/references/scripts.md and deployment-modes.md for progressive disclosure of package runner patterns and plugin cache isolation rules - Fix skill-audit Step 1 cross-skill path reference (was repo-absolute, now skill-relative); add manual fallback for sandboxed/Bash-denied contexts - Scope Step 2 "read every file" to exclude binaries and unreferenced files - Fix new-skill.sh next-steps output to reference /skill-audit instead of the removed validate.sh - Remove stale Dependencies section from skill-audit README; flip dependency arrow — skill-write depends on skill-audit, not vice versa Co-Authored-By: Claude Sonnet 4.6 --- .../kyberforge/skills/skill-audit/README.md | 7 +- .../kyberforge/skills/skill-audit/SKILL.md | 11 ++- .../scripts/validate.sh | 0 .../kyberforge/skills/skill-write/README.md | 17 +---- .../kyberforge/skills/skill-write/SKILL.md | 12 ++-- .../references/deployment-modes.md | 38 +++++++++++ .../skills/skill-write/references/scripts.md | 68 +++++++++++++++++++ .../skills/skill-write/scripts/new-skill.sh | 2 +- 8 files changed, 123 insertions(+), 32 deletions(-) rename plugins/kyberforge/skills/{skill-write => skill-audit}/scripts/validate.sh (100%) create mode 100644 plugins/kyberforge/skills/skill-write/references/deployment-modes.md create mode 100644 plugins/kyberforge/skills/skill-write/references/scripts.md diff --git a/plugins/kyberforge/skills/skill-audit/README.md b/plugins/kyberforge/skills/skill-audit/README.md index 7491031..75c8dd4 100644 --- a/plugins/kyberforge/skills/skill-audit/README.md +++ b/plugins/kyberforge/skills/skill-audit/README.md @@ -4,7 +4,7 @@ Audit a skill directory against the agentskills.io specification. Runs structura ## What it does -1. Runs `validate.sh` from `skill-write` for structural checks (name format, description length, line count, placeholder detection, script rules) +1. Runs `scripts/validate.sh` for structural checks (name format, description length, line count, placeholder detection, script rules) 2. Reads all files in the skill directory 3. Applies qualitative checks across seven dimensions 4. Outputs a PASS/FAIL/SUGGESTION punch list with a specific fix proposal for every FAIL @@ -22,8 +22,5 @@ Provide the path to the skill directory to audit when invoking. | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | +| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description length, line count, placeholder detection, script executable bit, and interactive-prompt detection | | `README.md` | This file | - -## Dependencies - -Requires `skill-write` to be installed at `plugins/kyberforge/skills/skill-write/` for the structural validation step. If not present, the agent performs structural checks manually. diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md index 2e4db4b..8ef52e8 100644 --- a/plugins/kyberforge/skills/skill-audit/SKILL.md +++ b/plugins/kyberforge/skills/skill-audit/SKILL.md @@ -16,19 +16,15 @@ metadata: ## Step 1 — Structural validation -Locate the `validate.sh` script from `skill-write`: - ```bash -bash plugins/kyberforge/skills/skill-write/scripts/validate.sh +bash scripts/validate.sh ``` -If `validate.sh` is not found, note it and proceed — perform the checks it would cover manually. - -List every FAIL from the structural check in the punch list before continuing. +List every FAIL from the structural check in the punch list before continuing. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled `FILL IN:` placeholders, scripts executable and free of interactive prompts. ## Step 2 — Read all skill files -Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, and `assets/`. Do not skip files — internal consistency checks require the full picture. +Read every file in the skill directory: `SKILL.md`, `README.md` (if present), all files in `scripts/`, `references/`, and `assets/`. Skip binary files and files not directly referenced from `SKILL.md`. Do not skip text files — internal consistency checks require the full picture. ## Step 3 — Qualitative audit @@ -66,6 +62,7 @@ Check each pattern is appropriate and correctly formed: - No non-spec files (e.g. META.md, extra config files) - Optional directories contain real content — not just unfilled placeholder READMEs - `README.md` present and accurately describes the skill and its files +- No cross-plugin path references — paths using `../`, `../../`, or absolute repo paths (e.g. `plugins/kyberforge/skills/...`) break when the plugin is installed to a cache; flag any found ### Formatting diff --git a/plugins/kyberforge/skills/skill-write/scripts/validate.sh b/plugins/kyberforge/skills/skill-audit/scripts/validate.sh similarity index 100% rename from plugins/kyberforge/skills/skill-write/scripts/validate.sh rename to plugins/kyberforge/skills/skill-audit/scripts/validate.sh diff --git a/plugins/kyberforge/skills/skill-write/README.md b/plugins/kyberforge/skills/skill-write/README.md index 27d8ed7..c8105da 100644 --- a/plugins/kyberforge/skills/skill-write/README.md +++ b/plugins/kyberforge/skills/skill-write/README.md @@ -18,31 +18,18 @@ This skill produces its best output when you arrive with rich context: ## Usage -Invoke via your agent tool with `/skill-write`, or follow the steps in `SKILL.md` manually. - -**Agent invocation:** ``` /skill-write ``` -**Manual (human) workflow:** -```bash -# 1. Create the scaffold -bash scripts/new-skill.sh - -# 2. Fill in the templates at // - -# 3. Validate -bash scripts/validate.sh / -``` - ## Files | File | Purpose | |------|---------| | `SKILL.md` | Skill instructions for agents | | `scripts/new-skill.sh` | Copies annotated templates to the destination | -| `scripts/validate.sh` | Validates a skill directory against the spec | +| `references/scripts.md` | Package runner table and inline dependency patterns (loaded on demand) | +| `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) | | `assets/templates/SKILL.md` | Annotated SKILL.md template | | `assets/templates/README.md` | Annotated README template for the new skill | | `assets/templates/scripts/README.md` | Placeholder for bundled scripts | diff --git a/plugins/kyberforge/skills/skill-write/SKILL.md b/plugins/kyberforge/skills/skill-write/SKILL.md index 8a403a9..ba46cf2 100644 --- a/plugins/kyberforge/skills/skill-write/SKILL.md +++ b/plugins/kyberforge/skills/skill-write/SKILL.md @@ -26,6 +26,8 @@ Share those outputs in this conversation: grill context, research docs, examples If any are missing, stop and ask the user before proceeding. +**Requires `/skill-audit`** — used in Step 5 for final validation. Both skills ship in the kyberforge plugin and are co-installed. If `/skill-audit` is unavailable, stop and ask the user to install the kyberforge plugin before continuing. + ## Step 1 — Scaffold Run the copy script with the skill name and destination directory: @@ -42,6 +44,8 @@ bash scripts/new-skill.sh data-analyzer plugins/myplugin/skills/ This creates `//` with annotated templates ready to fill in. +If the destination is inside a plugin directory (path contains a `plugin.json`), read `references/deployment-modes.md` before adding any file references to SKILL.md. + ## Step 2 — Fill in SKILL.md Open `//SKILL.md`. Replace every `FILL IN:` placeholder. @@ -130,6 +134,8 @@ Place executable scripts in `scripts/`. Rules for agentic scripts: - **Meaningful exit codes** — `0` success, non-zero failure; document in `--help` - **Dry-run support** — add `--dry-run` for destructive operations +If the skill needs scripts with external package dependencies or language-specific tooling (Python, TypeScript, Ruby, Go), read `references/scripts.md` for package runner patterns and inline dependency formats. + If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory. ## Step 4 — Add references and assets (if needed) @@ -144,8 +150,6 @@ If not needed, delete the placeholder READMEs and their directories. ## Step 5 — Validate -```bash -bash scripts/validate.sh / -``` +Run `/skill-audit` on `/`. -All checks must pass before the skill is considered done. +All FAIL findings must be resolved before the skill is considered done. diff --git a/plugins/kyberforge/skills/skill-write/references/deployment-modes.md b/plugins/kyberforge/skills/skill-write/references/deployment-modes.md new file mode 100644 index 0000000..8a8b7d7 --- /dev/null +++ b/plugins/kyberforge/skills/skill-write/references/deployment-modes.md @@ -0,0 +1,38 @@ +# Deployment Modes + +Skills deploy in two modes. Both resolve relative paths from the skill root — the SKILL.md body works the same in either. Differences only arise when referencing files *outside* the skill directory. + +## Cache isolation (plugin mode) + +When a plugin is installed, its directory is copied to a cache. Only the plugin's own files are copied. **Any path that leaves the skill directory breaks post-install:** + +``` +../other-skill/validate.sh # breaks +plugins/kyberforge/skills/other-skill/ # breaks +../../shared/utils.sh # breaks +``` + +Fix: duplicate the file into the skill's own `scripts/` or `assets/`. There is no plugin-level `shared/` mechanism — the spec defines no cross-skill sharing, and `../` paths are broken by construction. + +## Env vars (plugin mode only) + +These variables are injected when the plugin is loaded from an install cache. They are **not available in standalone mode.** + +| Variable | Value | +|----------|-------| +| `${CLAUDE_PLUGIN_ROOT}` | Absolute path to the plugin's install directory. Changes on update. | +| `${CLAUDE_PLUGIN_DATA}` | Persistent directory that survives updates. Use for `node_modules`, generated state, caches. | + +Use `${CLAUDE_PLUGIN_ROOT}` only in hook commands and `.mcp.json` configs — not in SKILL.md body text, since standalone deployments won't have it. + +## Standalone mode + +Deployed directly to `~/.agents/skills//`. No plugin context, no env vars injected. All file references must resolve within the skill directory. Skill invocations (e.g. `/skill-audit`) work if the called skill is also installed. + +## Cross-tool portability + +`SKILL.md` is portable — the same file works in Claude Code and Copilot CLI. Agent definitions and manifest files (`plugin.json`, `hooks.json`) are tool-specific and must be authored separately per tool. + +## Shared assets between skills + +If two skills in the same plugin need the same file, duplicate it into each skill's `assets/` or `scripts/`. Add a comment in both copies noting the mirror relationship so they stay in sync when the spec changes. diff --git a/plugins/kyberforge/skills/skill-write/references/scripts.md b/plugins/kyberforge/skills/skill-write/references/scripts.md new file mode 100644 index 0000000..7679680 --- /dev/null +++ b/plugins/kyberforge/skills/skill-write/references/scripts.md @@ -0,0 +1,68 @@ +# Scripts Reference + +## Package runners (no install required) + +When an existing package does what you need, use a runner directly in SKILL.md without writing a script file. + +| Runner | Language | Notes | +|--------|----------|-------| +| `uvx package@version` | Python | Recommended. Aggressive caching via uv. | +| `pipx run 'package==version'` | Python | Broader OS availability. | +| `npx package@version` | Node.js | Ships with npm/Node.js. | +| `bunx package@version` | Node.js | Bun environments only. | +| `deno run npm:package@version` | TypeScript | Requires permission flags (`--allow-read`, etc.). | +| `go run golang.org/x/...@version` | Go | Built into Go toolchain. | + +Always pin versions. Never use `pip install` or `npm install -g` at runtime — they are not idempotent and pollute the environment. + +## Inline dependency patterns + +Use these when the script requires packages but should remain a single portable file. + +**Python (PEP 723 + uv):** +```python +# /// script +# dependencies = [ +# "beautifulsoup4>=4.12,<5", +# ] +# requires-python = ">=3.12" +# /// +from bs4 import BeautifulSoup +``` +```bash +uv run scripts/extract.py +``` + +**TypeScript (Deno):** +```typescript +#!/usr/bin/env -S deno run +import * as cheerio from "npm:cheerio@1.0.0"; +``` +```bash +deno run scripts/extract.ts +``` + +**TypeScript (Bun):** +```typescript +#!/usr/bin/env bun +import * as cheerio from "cheerio@1.0.0"; +``` +```bash +bun run scripts/extract.ts +``` + +**Ruby (bundler/inline):** +```ruby +require 'bundler/inline' +gemfile do + source 'https://rubygems.org' + gem 'nokogiri', '~> 1.16' +end +``` +```bash +ruby scripts/extract.rb +``` + +## Output size + +Many harnesses truncate tool output beyond 10–30K characters. Default to a summary or a reasonable output limit. For scripts that can produce large output: support `--offset N` for pagination, or use `--output FILE` to write to disk and keep stdout clean. diff --git a/plugins/kyberforge/skills/skill-write/scripts/new-skill.sh b/plugins/kyberforge/skills/skill-write/scripts/new-skill.sh index 464e9bc..4b1b07b 100755 --- a/plugins/kyberforge/skills/skill-write/scripts/new-skill.sh +++ b/plugins/kyberforge/skills/skill-write/scripts/new-skill.sh @@ -84,4 +84,4 @@ echo " 1. Fill in $TARGET/SKILL.md — replace all FILL IN: placeholders" echo " 2. Add scripts to scripts/ if needed (or delete the directory)" echo " 3. Add docs to references/ if needed (or delete the directory)" echo " 4. Add resources to assets/ if needed (or delete the directory)" -echo " 5. Validate: bash $(dirname "${BASH_SOURCE[0]}")/validate.sh $TARGET" +echo " 5. Validate: run /skill-audit on $TARGET"