skill-edit-validation — Claude Code skill: what it does
skill-edit-validation sweeps test suites for stale assertions after modifying skill markdown files, preventing unexpected CI breaks.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a claude-codeWhat skill-edit-validation does
This workflow activates whenever wording changes inside .md documents located under .opencode/skills/, .claude/skills/, or .agents/skills/. It extracts former phrasing and scans TypeScript files across tests/ and src/ using rg.
Each hit is evaluated within a 10-line window. The skill verifies whether assertions still match new wording and flags negative checks that break unintentionally, like not.toContain('skip') tripping over newly added text. Whenever a test targets behavioral logic rather than an exact string contract, checks move into tests/helpers/skill-content-registry.ts.
All stale assertions are refreshed directly within the active changeset instead of deferring repairs to remote CI pipelines.
What it helps with
- locate stale string assertions across test files after editing skills
- stop test failures in CI caused by modified prompt wording
- refactor fragile string checks into semantic assertions inside test helpers
Example prompts for the agent
- I edited prompts in
.claude/skills/spec/SKILL.md. Run a sweep for broken test assertions - Check our TypeScript test files for stale string matches from the updated skill files
- Verify that changing phrases in
.agents/skills/did not break existing assertions intests/
How to install skill-edit-validation
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a claude-code2Manually: put the files in place
~/.claude/skills/skill-edit-validation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skill-edit-validation/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a codex2Manually: put the files in place
.agents/skills/skill-edit-validation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a cursor2Manually: put the files in place
.cursor/skills/skill-edit-validation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .opencode/skills/skill-edit-validation2Manually: put the files in place
.github/skills/skill-edit-validation/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .opencode/skills/skill-edit-validationManually: put the files in place
.devin/skills/skill-edit-validation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about skill-edit-validation
How to install skill-edit-validation in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill skill-edit-validation -a claude-code in your terminal.
What does skill-edit-validation do?
It identifies outdated string assertions across test files after skill wording updates and syncs them before pushing code.
Which directories trigger this validation sweep?
It inspects changes made to markdown files inside .opencode/skills/, .claude/skills/, and .agents/skills/.
Source text
SKILL.md · MIT
---
name: skill-edit-validation
description: Content-assertion sweep after editing SKILL.md files. Triggered when a task changes skill or prompt content that tests assert against. Prevents stale-assertion CI failures.
metadata:
audience: swarm-plugin
---
# Skill Edit Validation
## Trigger
After editing ANY `.md` file under `.opencode/skills/`, `.claude/skills/`, or `.agents/skills/` that changes content wording (not just whitespace/formatting).
## Protocol
1. **Extract changed phrases:** Identify old wording vs new wording (e.g., "spec.md does NOT exist" changed to "NO effective spec exists")
2. **Targeted sweep:** For each OLD phrase, grep test files:
```
rg "<old-phrase>" tests/ src/ --type ts -l
```
Focus on: `*-audit*`, `*-security*`, `*-spec-gate*`, `*skill-mirror*`, `*soft-spec*`, `*prompt*`, `*workflow*`
3. **For each match:** Read the assertion context (surrounding 10 lines). Verify:
- Does the assertion still hold against the new content?
- Is it checking a substring containing the old phrase?
- Is it checking for the ABSENCE of a word the new wording introduces? (e.g., `not.toContain('skip')` catches "this check is skipped")
4. **Prefer the semantic registry:** If the assertion is checking skill behavior
rather than an exact contract string, move it behind
`tests/helpers/skill-content-registry.ts` (or add a concept there) and assert
the named concept from the test.
5. **Update stale assertions in the same changeset.** Do NOT defer to CI.
6. **Preserve behavioral intent:** When updating, preserve what the assertion TESTS (e.g., "the plan skill has a spec-absent branch"), not just the string match.
## Constraint
Do NOT rubber-stamp brittle assertions. If an assertion tests implementation detail rather than behavioral intent, flag it for refactoring to a semantic check.
## Root cause
Skill-content tests should assert named semantic concepts where possible. The
registry in `tests/helpers/skill-content-registry.ts` is the preferred safety
net for recurring skill wording checks; use the manual grep sweep for exact
contract strings and any tests not yet migrated.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm