diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md index 37b694a..f350bf3 100644 --- a/plugins/kyberforge/skills/skill-audit/SKILL.md +++ b/plugins/kyberforge/skills/skill-audit/SKILL.md @@ -16,6 +16,10 @@ metadata: category: factory --- +## Gotchas + +- Do not output PASS/FAIL per check while auditing — gather findings internally and surface them only in the Step 4 report. Narrating each check as you go is the default failure mode here. + ## Step 1 — Structural validation ```bash @@ -30,7 +34,7 @@ Read every file in the skill directory: `SKILL.md`, `README.md` (if present), al ## Step 3 — Qualitative audit -Work through each dimension internally. Do not output PASS/FAIL per check — this is internal working. Collect findings only; report them in Step 4. Cite file and line number for every finding. +Work through each dimension internally. Collect findings only; report them in Step 4. Cite file and line number for every finding. ### Description @@ -69,7 +73,8 @@ Check each pattern is appropriate and correctly formed: - No non-spec files at the skill root (e.g. META.md, extra config files outside permitted directories) - 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 +- No cross-plugin path references in SKILL.md, scripts/, references/, or assets/ — paths using `../`, `../../`, or absolute repo paths (e.g. `plugins/kyberforge/skills/...`) break when the plugin is installed to a cache; flag any found +- `tests/` is exempt from the cross-plugin path check — test files are dev-only and may reference repo-level test infrastructure (e.g. a shared `tests/test_helper/`). This dependency must be declared in `tests/README.md`; flag if tests exist but `tests/README.md` is absent or does not document the dependency ### Formatting diff --git a/plugins/kyberforge/skills/skill-improve/SKILL.md b/plugins/kyberforge/skills/skill-improve/SKILL.md index a9867f2..ca17988 100644 --- a/plugins/kyberforge/skills/skill-improve/SKILL.md +++ b/plugins/kyberforge/skills/skill-improve/SKILL.md @@ -1,15 +1,15 @@ --- name: skill-improve description: > - Apply evidence-based improvements to an existing skill. 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. 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. + 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 diff --git a/plugins/kyberforge/skills/skill-write/README.md b/plugins/kyberforge/skills/skill-write/README.md index ce4af59..07a9198 100644 --- a/plugins/kyberforge/skills/skill-write/README.md +++ b/plugins/kyberforge/skills/skill-write/README.md @@ -36,7 +36,8 @@ This skill produces its best output when you arrive with rich context: | `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 — requires bats-support and bats-assert in the repo root's `tests/test_helper/` (see skill-audit's `tests/README.md` for setup) | +| `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 diff --git a/plugins/kyberforge/skills/skill-write/SKILL.md b/plugins/kyberforge/skills/skill-write/SKILL.md index b8d05a8..7a910a8 100644 --- a/plugins/kyberforge/skills/skill-write/SKILL.md +++ b/plugins/kyberforge/skills/skill-write/SKILL.md @@ -1,14 +1,14 @@ --- name: skill-write description: > - Author a new skill following the agentskills.io specification — scaffold the - directory structure from annotated templates, fill in SKILL.md and supporting - files, then validate the result. 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. Performs best when preceded by a grill session and - domain research. Do not use to update an existing well-formed skill, write - evals, or author agent definition files. + 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, write evals, or + author agent definition files. allowed-tools: Bash Read Write metadata: category: factory diff --git a/plugins/kyberforge/skills/skill-write/tests/README.md b/plugins/kyberforge/skills/skill-write/tests/README.md new file mode 100644 index 0000000..7b3e65f --- /dev/null +++ b/plugins/kyberforge/skills/skill-write/tests/README.md @@ -0,0 +1,28 @@ +# tests/ + +Test files for scripts bundled with this skill. + +## Dependencies + +Tests require [bats-support](https://github.com/bats-core/bats-support) and +[bats-assert](https://github.com/bats-core/bats-assert). The test files load +helpers from the repo root's `tests/test_helper/`. + +From the repo root: + +```bash +git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support +git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert +``` + +Run all tests for this skill (from the repo root): + +```bash +bats plugins/kyberforge/skills/skill-write/tests/ +``` + +## Files + +| File | Purpose | +|------|---------| +| `new-skill.bats` | Bats test suite for `scripts/new-skill.sh` |