refactor(kyberforge): make skill-write and skill-audit self-contained with shared resources
- 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 <noreply@anthropic.com>
This commit is contained in:
@@ -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 <skill-name> <destination-dir>
|
||||
|
||||
# 2. Fill in the templates at <destination-dir>/<skill-name>/
|
||||
|
||||
# 3. Validate
|
||||
bash scripts/validate.sh <destination-dir>/<skill-name>
|
||||
```
|
||||
|
||||
## 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 |
|
||||
|
||||
@@ -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 `<destination-dir>/<skill-name>/` 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 `<destination-dir>/<skill-name>/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 <destination-dir>/<skill-name>
|
||||
```
|
||||
Run `/skill-audit` on `<destination-dir>/<skill-name>`.
|
||||
|
||||
All checks must pass before the skill is considered done.
|
||||
All FAIL findings must be resolved before the skill is considered done.
|
||||
|
||||
@@ -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/<name>/`. 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.
|
||||
68
plugins/kyberforge/skills/skill-write/references/scripts.md
Normal file
68
plugins/kyberforge/skills/skill-write/references/scripts.md
Normal file
@@ -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.
|
||||
@@ -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"
|
||||
|
||||
@@ -1,179 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
cat <<EOF
|
||||
Usage: validate.sh <skill-dir>
|
||||
|
||||
Validate a skill directory against the agentskills.io specification.
|
||||
|
||||
Arguments:
|
||||
skill-dir Path to the skill directory containing SKILL.md.
|
||||
|
||||
Exit codes:
|
||||
0 All checks passed
|
||||
1 One or more checks failed
|
||||
EOF
|
||||
}
|
||||
|
||||
if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
|
||||
usage
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ $# -lt 1 ]]; then
|
||||
echo "Error: skill-dir is required." >&2
|
||||
echo "" >&2
|
||||
usage >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
python3 -u - "$1" <<'PYTHON'
|
||||
import sys
|
||||
import os
|
||||
import re
|
||||
|
||||
skill_dir = os.path.abspath(sys.argv[1])
|
||||
skill_md = os.path.join(skill_dir, "SKILL.md")
|
||||
|
||||
if not os.path.isfile(skill_md):
|
||||
print(f"Error: '{skill_md}' not found.", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
with open(skill_md) as f:
|
||||
content = f.read()
|
||||
|
||||
failed = False
|
||||
|
||||
def ok(msg):
|
||||
print(f"PASS {msg}")
|
||||
|
||||
def fail(msg):
|
||||
global failed
|
||||
print(f"FAIL {msg}", file=sys.stderr)
|
||||
failed = True
|
||||
|
||||
# --- Parse frontmatter ---
|
||||
fm_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if not fm_match:
|
||||
fail("No valid YAML frontmatter block found (expected ---...---)")
|
||||
sys.exit(1)
|
||||
|
||||
fm = fm_match.group(1)
|
||||
body_start = fm_match.end()
|
||||
|
||||
# Extract name
|
||||
name_m = re.search(r'^name:\s*(\S+)', fm, re.MULTILINE)
|
||||
name = name_m.group(1).strip('"\'') if name_m else ""
|
||||
|
||||
# Extract description — inline or block scalar (> or |)
|
||||
desc = ""
|
||||
desc_m = re.search(r'^description:\s*([>|])\n((?:[ \t]+.+\n?)+)', fm, re.MULTILINE)
|
||||
if desc_m:
|
||||
raw = desc_m.group(2)
|
||||
desc = re.sub(r'\s+', ' ', raw).strip()
|
||||
else:
|
||||
desc_inline = re.search(r'^description:\s*(.+)', fm, re.MULTILINE)
|
||||
if desc_inline:
|
||||
desc = desc_inline.group(1).strip()
|
||||
|
||||
dir_name = os.path.basename(skill_dir)
|
||||
|
||||
# --- Checks ---
|
||||
|
||||
# name present
|
||||
if name:
|
||||
ok(f"name present: '{name}'")
|
||||
else:
|
||||
fail("name field is missing or empty")
|
||||
|
||||
# name matches directory
|
||||
if name and dir_name:
|
||||
if name == dir_name:
|
||||
ok(f"name '{name}' matches directory '{dir_name}'")
|
||||
else:
|
||||
fail(f"name '{name}' does not match directory '{dir_name}'")
|
||||
|
||||
# name length
|
||||
if name:
|
||||
if len(name) <= 64:
|
||||
ok(f"name length {len(name)} chars (limit: 64)")
|
||||
else:
|
||||
fail(f"name '{name}' is {len(name)} chars — exceeds 64-character limit")
|
||||
|
||||
# name format
|
||||
if name:
|
||||
if re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name):
|
||||
ok(f"name format valid (kebab-case)")
|
||||
else:
|
||||
fail(f"name '{name}' is invalid — use lowercase letters, numbers, and hyphens only; no leading, trailing, or consecutive hyphens")
|
||||
|
||||
# description present
|
||||
if desc:
|
||||
ok(f"description present")
|
||||
else:
|
||||
fail("description field is missing or empty")
|
||||
|
||||
# description length
|
||||
if desc:
|
||||
dlen = len(desc)
|
||||
if dlen <= 1024:
|
||||
ok(f"description length {dlen} chars (limit: 1024)")
|
||||
else:
|
||||
fail(f"description length {dlen} chars — exceeds 1024-character limit")
|
||||
|
||||
# Unfilled placeholder detection — matches FILL IN: followed by actual content,
|
||||
# but not backtick-quoted references like `FILL IN:` used in instructions.
|
||||
PLACEHOLDER_RE = re.compile(r'(?<!`)FILL IN:[^`\n]')
|
||||
|
||||
# description contains unfilled placeholder
|
||||
if desc and PLACEHOLDER_RE.search(desc):
|
||||
fail("description still contains 'FILL IN:' placeholder — replace before shipping")
|
||||
else:
|
||||
if desc:
|
||||
ok("description has no unfilled placeholders")
|
||||
|
||||
# SKILL.md line count
|
||||
line_count = len(content.splitlines())
|
||||
if line_count <= 500:
|
||||
ok(f"SKILL.md line count {line_count} (limit: 500)")
|
||||
else:
|
||||
fail(f"SKILL.md line count {line_count} — exceeds 500-line limit")
|
||||
|
||||
# Body unfilled placeholders
|
||||
body = content[body_start:]
|
||||
fill_matches = PLACEHOLDER_RE.findall(body)
|
||||
if fill_matches:
|
||||
fail(f"SKILL.md body contains {len(fill_matches)} unfilled 'FILL IN:' placeholder(s)")
|
||||
else:
|
||||
ok("SKILL.md body has no unfilled placeholders")
|
||||
|
||||
# Scripts checks
|
||||
scripts_dir = os.path.join(skill_dir, "scripts")
|
||||
if os.path.isdir(scripts_dir):
|
||||
scripts = [f for f in os.listdir(scripts_dir)
|
||||
if os.path.isfile(os.path.join(scripts_dir, f)) and not f.endswith('.md')]
|
||||
for fname in scripts:
|
||||
fpath = os.path.join(scripts_dir, fname)
|
||||
with open(fpath) as f:
|
||||
sc = f.read()
|
||||
# Interactive prompt heuristic
|
||||
if re.search(r'^\s*(read\s|input\()', sc, re.MULTILINE):
|
||||
fail(f"scripts/{fname}: may use interactive input (read/input detected)")
|
||||
else:
|
||||
ok(f"scripts/{fname}: no interactive prompts detected")
|
||||
# Executable bit
|
||||
if os.access(fpath, os.X_OK):
|
||||
ok(f"scripts/{fname}: is executable")
|
||||
else:
|
||||
fail(f"scripts/{fname}: not executable — run: chmod +x {fpath}")
|
||||
|
||||
# Summary
|
||||
print()
|
||||
if not failed:
|
||||
print("All checks passed.")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print("One or more checks failed.", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
PYTHON
|
||||
Reference in New Issue
Block a user