skill-validator
/skill-validator
Write, review, debug or evolve an agent skill. Use to create or edit a SKILL.md, improve a description, fix a missed or wrong activation, or test a skill before it ships. For the format check only, use agentskills-checker.
- Author
- piabrota ↗
- Repository
- skills ↗
- Licence
- MPL-2.0
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MPL-2.0, otwarta.
What it does and when to use it
Write, review, debug or evolve an agent skill. Use to create or edit a SKILL.md, improve a description, fix a missed or wrong activation, or test a skill before it ships. For the format check only, use agentskills-checker.
Original author description
Write, review, debug or evolve an agent skill. Use to create or edit a SKILL.md, improve a description, fix a missed or wrong activation, or test a skill before it ships. For the format check only, use agentskills-checker.
How it works
- Modes
- First checks
- Write
- Review
- Debug
- Evolve
- Test
- Ship checklist
SKILL.md preview
--- name: skill-validator description: "Write, review, debug or evolve an agent skill. Use to create or edit a SKILL.md, improve a description, fix a missed or wrong activation, or test a skill before it ships. For the format check only, use agentskills-checker." license: MIT --- # skill-validator A skill costs tokens in each session and in each use. It must add what the agent does not know. Select a mode, then follow its steps. Read `references/rules.md` when you write or review a body. Read `references/evals.md` when you test or evolve a skill. ## Modes - **Write**: the skill does not exist. - **Review**: the skill exists, and the request is a quality verdict. - **Debug**: the skill does not start, starts at the wrong time, or gives a wrong result. - **Evolve**: the skill works, and real use shows gaps. ## First checks 1. Search the skills folder for a skill with the same job. If one exists, improve it. 2. Read the rules of the repository. They can set stricter limits than this skill. 3. In the repository of this skill, also obey these limits: - Each description has at most 300 characters. Each `SKILL.md` has at most 150 lines. - The text is in ASD-STE100. A skill body has no links, no credits and no history. - `README.md` and `www/tags.txt` need one entry for each new skill. ## Write 1. **Find the gap.** Run the agent on real tasks. A skill candidate is a place where it fails again or needs the same correction. 2. **Select the pattern.** - Capability: the agent cannot do X. Write a thin wrapper of a script or CLI. - Process: the output or the method of the agent is bad. Write a procedure with checks. 3. **Write the description first.** Use this pattern: `[Capability]. Use for [tasks or situations].` Add a boundary only if it prevents confusion with a related skill. 4. **Write the smallest body that works.** Use real material: runbooks, fixes and past failures. Add a line only when a test shows the gap. 5. **Move detail out.** Put long data in `references/`, and fragile steps in `scripts/`. Say when the agent must read or run each file. 6. **Test** as the `Test` section says. Then do the `Ship checklist`. ## Review 1. Run `agentskills-checker` on the skill folder. 2. Read each file of the skill, with `references/rules.md` next to it. 3. Report each finding with its file, its line, the rule and a fix. Sort them by cost to the user. 4. Do the `Ship checklist`. Report each item that fails. Do not change the skill unless the request asks for a change. ## Debug Find the failure class first. The fix is different for each class. | Symptom | Likely cause | Fix | |---|---|---| | The client does not list the skill | Invalid YAML, or a `name` that is not the folder name | Run `agentskills-checker` | | The skill does not start | The description is vague or has the wrong terms | Name real tasks, inputs and file types | | The skill starts at the wrong time | The description is too wide | Add a boundary | | The skill starts, but the result is wrong | The body has a gap | Add a step, an example or a check | | The result changes between runs | The body is ambiguous | Add an example, or move the step to a script | Then apply these rules: - Examine whether the runtime loaded `SKILL.md`. Valid YAML is not proof, and the report of an agent is not proof. - Use a new session for each activation test, because some clients read skills only at start. - Test on the weakest model that you will use. A strong model hides a vague skill. ## Evolve 1. Collect the signals: the failures, the corrections of the user, and the traces of real runs. 2. Keep a copy of the current version as the baseline. 3. Change the smallest part that explains the most signals. Fix the cause, not one prompt. 4. Remove each instruction that the traces show as wasted work. 5. If runs write the same helper again and again, put it in `scripts/`. 6. Run the tests against the baseline. Keep the change only if the results are better. 7. Stop when the results do not improve, or when the reviews show no problems. ## Test Test the two parts separately. `references/evals.md` gives the formats. - **Activation**: use realistic requests that do not name the skill. Also use near misses, which share keywords but must not start the skill. - **Execution**: start the skill by name, and compare the result with a run without the skill. - **Adversarial**: ask a second model which edge cases break the skill. Fix the real ones. ## Ship checklist Report each item as pass, fail or not tested. Do not mark an item pass without evidence. - [ ] `agentskills-checker` exits 0. - [ ] The description starts with the capability and has real triggers. - [ ] A boundary separates the skill from each related skill that can compete with it. - [ ] The skill does one job and composes with related skills. - [ ] The folder has no README, changelog or install guide. - [ ] The text has no fact that a date can make false. - [ ] Each path is relative and uses forward slashes. - [ ] Each step that needs a state checks the state first. - [ ] Each step that can fail says how to see the failure and what to do. - [ ] The skill states a verify, fix and verify again loop. - [ ] The skill shows the output format, if another tool reads the output. - [ ] Activation and execution are tested, on a weak model and on a strong model. - [ ] The change is in version control and is reviewed.
Files in this package (4)
- LICENSE 1 KB
- SKILL.md 5 KB
- references/evals.md 3 KB
- references/rules.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · piabrota/skills | 100 | MPL-2.0 |
| joaquimscosta/arkhe-claude-plugins | 100 | MIT |
Database snapshot: 13.11.2026 · package version 6b0c95fa3fe6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100skill-creator
Creates, reviews, fixes, and validates Agent Skills that conform to the agentskills.io specification. Use whenever the user wants to create a new agent skill, write or edit a SKILL.md, turn a workflow, prompt, or documentation into a reusable skill, restructure an oversized… - 100test-skill-activation
Measure whether agent skills (SKILL.md) actually activate in Claude Code, Codex and OpenCode with doesitfire, then improve the descriptions of skills that do not fire or fire when they should not. Use when the user asks if a skill triggers, why a skill is ignored, to test or… - 100write-skill
Write, improve or test a Blueprint skill (a SKILL.md whose description makes the agent load it at the right moment and whose body says why), and check it with and without the skill. Use it to turn a way of working into a skill, or when a skill is not used or used at the wrong time. - 100skill-creator
Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory (moving files to references/ or… - 100skill-creator
Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory (moving files to references/ or… - 90skill-review
Review an Agent Skill against the agentskills.io best practices. Use when creating or changing a SKILL.md, before publishing it, or when a skill under-performs.