From 7ec34dd0de064a375483c13faec49fae1ac86469 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Wed, 24 Jun 2026 19:18:50 +0000 Subject: [PATCH] fix(kyberforge): improve skill-author based on spec validation and audit - Add name field format constraints (1-64 chars, hyphens rules) - Add output format template pattern to ## Patterns - Add scope design note before prerequisites checklist - Add reference depth rule (one level deep) - Restore Placement table to README - Trim script rules to 2 inline + full contract in references/scripts.md - Add script contract section to references/scripts.md (error messages, dry-run/confirm pairing, output size, idempotency, exit codes) - Update Step 5 headings to "Validate and close" in both flows - Remove "Performs best when preceded by grill session" from description - Condense Include/Exclude block to single forwarding sentence - Fix README Files table: add README.md row, update scripts.md description Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_016z2ZFYHQCex8yZAMVMTZzZ --- .../kyberforge/skills/skill-author/README.md | 12 ++++- .../kyberforge/skills/skill-author/SKILL.md | 45 +++++++++---------- .../skills/skill-author/references/scripts.md | 11 +++++ 3 files changed, 42 insertions(+), 26 deletions(-) diff --git a/plugins/kyberforge/skills/skill-author/README.md b/plugins/kyberforge/skills/skill-author/README.md index c76dab2..94ac0dd 100644 --- a/plugins/kyberforge/skills/skill-author/README.md +++ b/plugins/kyberforge/skills/skill-author/README.md @@ -12,6 +12,15 @@ Routes to one of two flows based on context: if no skill directory exists at the - Collect domain research, examples, and constraints - Know the skill name (kebab-case) and destination path +## Placement + +| Type | Path | +|------|------| +| Direct (available immediately after install) | `~/.agents/skills//` | +| Plugin (installed via marketplace) | `plugins//skills//` | + +If the destination is inside a plugin directory, read `references/deployment-modes.md` — cache isolation rules apply. + ## Usage ``` @@ -22,10 +31,11 @@ Routes to one of two flows based on context: if no skill directory exists at the | File | Purpose | |------|---------| +| `README.md` | Human-readable overview of the skill and its files | | `SKILL.md` | Skill instructions for agents | | `scripts/new-skill.sh` | Copies annotated templates to the destination to scaffold a new skill | | `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) | -| `references/scripts.md` | Package runner table and inline dependency patterns (loaded on demand) | +| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (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-author/SKILL.md b/plugins/kyberforge/skills/skill-author/SKILL.md index 9ef83bc..58cc086 100644 --- a/plugins/kyberforge/skills/skill-author/SKILL.md +++ b/plugins/kyberforge/skills/skill-author/SKILL.md @@ -8,8 +8,7 @@ description: > provides inline feedback about a skill's behavior and wants it applied, or when a grill session, eval run, or audit has produced findings the user wants acted on — even if they don't say "improve" explicitly. Authors and refines - skills following the agentskills.io specification. Performs best when preceded - by a grill session and domain research. Do not use for read-only review — use + skills following the agentskills.io specification. Do not use for read-only review — use /skill-audit instead. Do not use to author agent definition files. allowed-tools: Bash Read Write Edit metadata: @@ -38,6 +37,8 @@ Signals include: grill session output, `/skill-audit` findings (PASS/FAIL punch Run `/grill-me` on the skill's design and research the target domain first. Share those outputs in this conversation: grill context, research docs, examples, constraints. +Design for one coherent user intent — skills too narrow force multiple loads per task; too broad are hard to activate precisely. + **Before touching the filesystem, verify you have:** - [ ] A clear purpose — what specific task will this skill handle? - [ ] Trigger scenarios — when should an agent activate it, including indirect cases? @@ -71,7 +72,7 @@ Open `//SKILL.md`. Replace every `FILL IN:` placeho #### Frontmatter -**`name`** — already set by the scaffold script. Must exactly match the directory name. +**`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters/numbers/hyphens only, no leading, trailing, or consecutive hyphens (`--`). **`description`** — carries the entire triggering burden. Rules: - Imperative: "Use when..." not "This skill..." @@ -91,19 +92,7 @@ Open `//SKILL.md`. Replace every `FILL IN:` placeho Rename the placeholder section heading to one that fits the skill's structure — `## Step 1`, `## Workflow`, `## Instructions`, etc. -Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no." - -**Include:** -- Non-obvious sequences or ordering constraints — the agent may skip or reorder steps without this -- Domain conventions the agent cannot infer from general knowledge — this is the core value a skill adds -- One default per decision point, plus one escape hatch — never a menu; menus cause the agent to pause or pick arbitrarily -- Gotchas — facts that defy reasonable assumptions; the agent will get these wrong every time without them - -**Exclude:** -- Concepts the agent already knows (what JSON is, how HTTP works) — adds tokens without changing behavior -- Exhaustive option lists — pick a default; the agent doesn't benefit from choosing -- Steps the agent handles independently — over-specifying leads agents to follow unproductive paths -- Restatements of the description — it's already in context; repeating it wastes the token budget +Follow body discipline: one default per decision point, no menus, gotchas near the top. Ask of every sentence: "Would the agent get this wrong without it?" Cut anything that answers "no." #### Patterns @@ -139,6 +128,16 @@ Do not modify flags. If , read `references/.md`. ``` +**Output format template** (when the skill produces structured output): +```markdown +Output format: +\`\`\` +: +: +\`\`\` +``` +For longer templates, place in `assets/.md` and reference conditionally. + #### Size budget Keep `SKILL.md` under 500 lines and 5,000 tokens. When approaching the limit: @@ -147,17 +146,12 @@ Keep `SKILL.md` under 500 lines and 5,000 tokens. When approaching the limit: ### Step 3 — Add scripts (if needed) -Place executable scripts in `scripts/`. Rules for agentic scripts: +Place executable scripts in `scripts/`. Two critical rules: -- **Self-contained** — bundle dependencies inline so the agent can run the script with a single command; do not require a separate install step - **No interactive prompts** — agents run non-interactive; blocking on TTY input hangs indefinitely. Accept all input via flags, env vars, or stdin. - **Expose `--help`** — concise usage output; keep it short (it enters the agent's context) -- **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr -- **Idempotent** — "create if not exists"; agents may retry on failure -- **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. +For the full script contract (self-contained deps, structured output, idempotency, exit codes, dry-run, error messages, output size), read `references/scripts.md`. If no scripts are needed, delete `scripts/README.md` and the `scripts/` directory. @@ -165,6 +159,7 @@ If no scripts are needed, delete `scripts/README.md` and the `scripts/` director **`references/`** — additional documentation loaded on demand. One topic per file. Reference conditionally from SKILL.md: `If , read references/.md`. +Keep reference chains one level deep — a reference file that references another reference file is rarely loaded correctly. **`assets/`** — static resources: templates, schemas, lookup tables. Reference by relative path from SKILL.md. @@ -175,7 +170,7 @@ not in `scripts/`. See `tests/README.md` for setup instructions. If not needed, delete the placeholder READMEs and their directories. -### Step 5 — Validate +### Step 5 — Validate and close Run `/skill-audit` on `/`. @@ -231,6 +226,6 @@ If a signal points to a script or reference file, edit that file directly rather **On scripts**: Fix and edit existing scripts freely when signals point to them. -### Step 5 — Validate +### Step 5 — Validate and close Run `/skill-audit` on the skill directory. Resolve any FAIL findings before considering the improvement complete. diff --git a/plugins/kyberforge/skills/skill-author/references/scripts.md b/plugins/kyberforge/skills/skill-author/references/scripts.md index 7679680..7cff2f1 100644 --- a/plugins/kyberforge/skills/skill-author/references/scripts.md +++ b/plugins/kyberforge/skills/skill-author/references/scripts.md @@ -63,6 +63,17 @@ end ruby scripts/extract.rb ``` +## Script contract + +Rules for all agentic scripts: + +- **Self-contained** — bundle dependencies inline so the agent can run the script with a single command; do not require a separate install step +- **Structured output** — data (JSON, CSV) to stdout; diagnostics and progress to stderr +- **Idempotent** — "create if not exists"; agents may retry on failure +- **Meaningful exit codes** — `0` success, non-zero failure; document in `--help` +- **Dry-run support** — add `--dry-run` for destructive operations; pair with `--confirm`/`--force` for operations that can't be undone +- **Error messages** — on failure, state what went wrong, what was expected, and what to try; vague errors leave agents unable to self-correct + ## 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.