diff --git a/plugins/kyberforge/skills/skill-improve/README.md b/plugins/kyberforge/skills/skill-improve/README.md deleted file mode 100644 index ac299b2..0000000 --- a/plugins/kyberforge/skills/skill-improve/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# skill-improve - -Apply evidence-based improvements to an existing skill using signals from the current session. - -## What it does - -Takes an existing skill directory and one or more improvement signals — grill output, audit findings, eval failures, human feedback, or inline session context — and applies targeted edits to the skill files. Groups signals by root cause before editing to avoid per-symptom patching. Hands off to `/skill-audit` when done. - -## Before you start - -Have at least one improvement signal ready: a grill session output, `/skill-audit` report, eval results, feedback.json, or inline feedback describing what went wrong. If you have no signals and want a blind review, use `/skill-audit` instead. - -## Usage - -``` -/skill-improve -``` - -Provide the skill directory path and any signal files in the conversation. The skill gathers signals from context — you don't need to paste them in a specific format. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | diff --git a/plugins/kyberforge/skills/skill-improve/SKILL.md b/plugins/kyberforge/skills/skill-improve/SKILL.md deleted file mode 100644 index ca7790a..0000000 --- a/plugins/kyberforge/skills/skill-improve/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: skill-improve -description: > - Use when the user says "improve this skill", "fix this skill based on - feedback", "apply these audit findings", or "update the skill based on this - grill output". Also use when the user 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. Applies evidence-based improvements to an existing skill. Do not - use when the user wants a read-only review only — use /skill-audit instead. - Do not use when no improvement signals are present in the conversation or - referenced files. -allowed-tools: Bash Read Write Edit -metadata: - category: factory ---- - -## Gotchas - -- Patching per symptom is the default failure mode. Three eval failures may all trace to one missing instruction — always identify the root cause before editing. -- Do not create new scripts unless a signal explicitly calls for it. Writing scripts from scratch requires transcript analysis that is out of scope here; flag the opportunity as a suggestion instead. - -## Step 1 — Verify inputs - -Confirm the skill directory path exists and that at least one improvement signal is present in the conversation or a referenced file. - -If the skill dir is missing, ask for it. If no signals are present, stop: "This skill applies existing signals to a skill. For a blind review without signals, use `/skill-audit` instead." - -Signals can come from anywhere in the conversation or referenced files: -- Grill session output (most common predecessor in the factory sequence) -- `/skill-audit` findings (PASS/FAIL/SUGGESTION punch list) -- Human feedback (feedback.json, inline in conversation, PR or issue comments) -- Session context describing what went wrong - -## Step 2 — Gather and group signals - -Read the current skill files (SKILL.md and any files in scripts/, references/, assets/, tests/). Then collect all signals from the conversation and any file paths the user has referenced. - -Group signals by **root cause**, not symptom. Ask: "What single gap in the skill causes this cluster of failures?" One root cause → one fix. Do not make a separate edit for each symptom. - -```text -Example: -- Session context: output format is wrong on every run -- Audit finding: no output template defined -- User feedback: "I always have to ask it to format the output" -→ Root cause: SKILL.md has no output format specification → one fix: add an output template -``` - -## Step 3 — Announce planned changes - -Before editing, state: -- Which root causes were identified and what evidence supports each -- Which files will be changed and what will change in each - -Then proceed — edits are reversible via git, no approval checkpoint needed. - -## Step 4 — Apply changes - -Edit any file in the skill directory that the signals point to: SKILL.md, scripts/, references/, assets/, tests/, README.md. - -**Generalize, don't patch.** Find the underlying gap, not the specific example that failed. A fix scoped only to the test cases you've seen will overfit and perform worse on new inputs. - -**Keep it lean.** Remove instructions that aren't pulling their weight. For every sentence you add, ask: "Would the agent get this wrong without it?" A shorter, focused skill consistently outperforms an exhaustive one. - -**Explain the why.** Reasoning-based instructions outperform rigid directives. If you find yourself writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the agent can apply judgment in edge cases. - -If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md. - -**On scripts**: Fix and edit existing scripts freely when signals point to them. - -## 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-write/README.md b/plugins/kyberforge/skills/skill-write/README.md deleted file mode 100644 index 07a9198..0000000 --- a/plugins/kyberforge/skills/skill-write/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# skill-write - -Author a new skill conforming to the [agentskills.io](https://agentskills.io) specification. - -## What it does - -1. Scaffolds a full skill directory from annotated templates -2. Guides filling in `SKILL.md` and supporting files -3. Validates the result against the spec - -## Before you start - -This skill produces its best output when you arrive with rich context: - -- Run `/grill-me` to resolve design decisions (scope, triggers, patterns) -- Collect domain research, examples, and reference docs -- Know the skill name (kebab-case) and destination path - -## Usage - -``` -/skill-write -``` - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/new-skill.sh` | Copies annotated templates to the destination | -| `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 | -| `assets/templates/references/README.md` | Placeholder for reference docs | -| `assets/templates/assets/README.md` | Placeholder for static assets | -| `assets/templates/tests/README.md` | Placeholder for test files | -| `tests/new-skill.bats` | Bats test suite for new-skill.sh | -| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies | - -## Placement - -Skills can be installed in two locations: - -| Type | Path | -|------|------| -| Direct (available immediately) | `~/.agents/skills//` | -| Plugin (installed via marketplace) | `plugins//skills//` | - -## Spec reference - -[agentskills.io specification](https://agentskills.io/specification.md) diff --git a/plugins/kyberforge/skills/skill-write/SKILL.md b/plugins/kyberforge/skills/skill-write/SKILL.md deleted file mode 100644 index 6b86d05..0000000 --- a/plugins/kyberforge/skills/skill-write/SKILL.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -name: skill-write -description: > - Use when the user wants to create a new skill from scratch, says "write a skill - for X", "build a skill that does Y", or "create a SKILL.md for Z", or wants to - make a workflow repeatable or shareable as a reusable command. Authors a new - skill following the agentskills.io specification — scaffolds the directory - structure from annotated templates, fills in SKILL.md and supporting files, then - validates the result. Performs best when preceded by a grill session and domain - research. Do not use to update an existing well-formed skill — use /skill-improve - instead. Do not use to author agent definition files. -allowed-tools: Bash Read Write -metadata: - category: factory ---- - -## Prerequisites - -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. - -**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? -- [ ] Skill name (kebab-case) and destination path - -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: - -```bash -bash scripts/new-skill.sh -``` - -Examples: -```bash -bash scripts/new-skill.sh my-tool ~/.agents/skills/ -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. - -### Frontmatter - -**`name`** — already set by the scaffold script. Must exactly match the directory name. - -**`description`** — carries the entire triggering burden. Rules: -- Imperative: "Use when..." not "This skill..." -- Specific about capabilities ("parses and validates OpenAPI specs", not "helps with APIs") -- Include indirect triggers: "even if the user doesn't mention X explicitly" -- Add "Do not use when..." only if a near-miss skill exists that could steal activations -- Hard limit: 1024 characters — count before finalizing - -**Optional fields** — uncomment and fill in or remove entirely: -- `license` — include when distributing the skill externally -- `compatibility` — include if the skill requires specific tools, runtimes, or network access -- `metadata` — key-value map; use `author`, `version`, `category` -- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts - -### Body — include only what the agent lacks - -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 - -### Patterns - -**Gotchas** — highest value; place near the top: -```markdown -## Gotchas -- --