skill-standards
Use when writing, reviewing, refactoring, or cutting a skill, agent, or command prompt in this marketplace: how it opens, what its description must do, what the body holds, and the eval that decides whether it is kept. Triggers: write a skill, review this skill, improve this skill, is this skill any good, skill description, should this be a skill, write an agent prompt, napis skill, zkontroluj skill. The prompting guide is the prompting skill; building one into a plugin is add-skill; the file contract of a plugin is the add-plugin skill.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-standards
- description
- Use when writing, reviewing, refactoring, or cutting a skill, agent, or command prompt in this marketplace: how it opens, what its description must do, what the body holds, and the eval that decides whether it is kept. Triggers: write a skill, review this skill, improve this skill, is this skill any good, skill description, should this be a skill, write an agent prompt, napis skill, zkontroluj skill. The prompting guide is the prompting skill; building one into a plugin is add-skill; the file contract of a plugin is the add-plugin skill.
03 SKILL.md 正文
Skill Standards
The agent that reads a skill has none of our context. Give it why the skill exists and what done looks like, and it decides well in the case the skill never named. This is the bar for a skill, an agent or a command prompt. The prompting guide is the prompting skill, building one into a plugin is add-skill. The scope is always smaller than the agent thinks: the simplest version that does the job is the right one.
Shape
| Part | Holds |
|---|---|
| description | the trigger, in the words a user types |
| opening | the purpose: the gap, who it serves, the outcome, what it will not do |
| body | the maintainer's stance, thresholds, commands, each rule with its reason |
## Red flags |
symptoms the agent can notice, each with action and reason |
## Say it in the reply |
what the reply must show |
One sentence lives in one part. Move a repeat, do not copy it.
Rules
- Description: third person, key case first, then phrases a user types, under 1,024 characters. Name the neighbour skill that owns what this one does not, because two descriptions matching one request is a coin flip.
- Cut every line the model already knows. A skill holds only what the model does not do unaided: our stance, our numbers, our commands. A skill whose eval delta is zero is cut.
- Plain words, no capitals for emphasis, no MUST. A shouted rule is applied wider than meant.
- Give the reason with each rule. A rule with no reason is deleted.
- Prefer one positive example to a list of "never" lines.
- A constraint that must hold every time is a hook, and the skill names the hook.
- A skill that tells an agent to test says: the least work that runs the real path end to end, never a test that restates what was just written.
- One subject per skill, cap 12 KB, aim for 8, no
references/. Over the cap: split into two. - No dates, no history, no test evidence in the body.
Evals
Every skill and agent ships an eval, written before the body, so the first run shows what the
model does unaided. A skill without one is not merged, because an unproven skill may never load or
may change nothing. The cases live under the plugin's evals/, one folder each, tagged in
case.yaml when the case has one, else in the prompt's frontmatter:
| Tag | What it proves | Grader | Runs |
|---|---|---|---|
fire |
the skill loads on the words a user types | tool_used on Skill, or a regex on the named agent |
with only, max_turns: 2 (an agent 4) |
scenario |
the skill changes how the agent works on a hard problem | one to three points | with and without |
negative |
the skill stays quiet on an unrelated ask, one per plugin | tool_used on Skill with max: 0 |
with only, max_turns: 2 |
Map the skill into its steps first: fire, probe, decide, act, report. A step that code could do is
checked deterministically; only a judgement gets an llm point. The step that fails first is the
one to fix, often one sentence where the skill says nothing.
A scenario is a hard interview question answered from the head. It opens by naming the skill
(Use the debugging skill.), because firing is the fire case's job and a scenario that never loads
its skill measures nothing. It plants a situation with a known answer and its traps: a symptom far
from its cause, a claim someone relayed that is wrong, a change that looks safe. Information may be
incomplete on purpose; the grade is where the agent would look, why, what it connects, what it
does first, and how it would prove it. The reply has a fixed shape, Approach:, Flow:,
Next step:, plus Report: when the work is handed to someone. Never ask the model to think out
loud or name a field Thinking:: the API refuses it as reasoning extraction. Execute for real only
where the tool call is the value (closing a task, searching the archive, keeping a log).
The grader judges the thought process and the output, in one to three points:
- Grade only what the skill changes. A point the plain model passes as easily is deleted, not reworded, because it measures nothing.
- Grade only what the prompt makes necessary, and give both arms the words the answer is graded
in (
fix,scoped,multi-session), so the point falls on the decision, not the vocabulary. - Prefer a regex on a planted answer to an
llmpoint. A regex is case-insensitive (flags: i; an inline(?i)throws), and its case carriessamples/pass.mdandsamples/fail.md: the eval runner refuses to spend a run until every regex matches the pass and misses the fail. - An
llmgrader opens withIntent of this eval: <one or two sentences>: the situation the person is in and what behaviour would make them trust the skill. The judge reads it first and the lens shows it as the case summary. - An
llmpoint judges the reply (focus: last_message), because a scenario asks the agent to say in words what it would do and why, and a long trace buries that reply under tool output. Grade a tool call withtool_used, not a judge over the trace. The trace is for debugging a failed case (--keep-temp). - Read a failing reply before trusting the grader: a worker that found a better path than the one the case planted is a case to fix, not a skill.
When the sandbox lacks what the job needs (web, git, the task tool), the prompt says so to both arms and the grade falls on the plan. The bar: every run with the plugin passes (3 of 3) and at most one without does.
Working the lens edits
The person edits a skill, an agent or a plugin text on the marketplace lens. Saving makes one task
and writes no file, so the work is yours, with them. When a task of kind edit reaches you (the hook
shows it, or qsm-builder lens tasks <plugin> lists it):
- Check it is current. A task marked stale names a file that changed after the edit was made, so read the file now and say what differs. Never apply a stale task as it is.
- Show the person three things: the text before, the text after, and their note. Then say what you
would do, or why you refuse. A
SKILL.mdthat would pass 12 KB is a split. A change of behaviour goes throughspec-proposefirst. An edit that breaks a rule above is proposed again in better words, with the reason. - Ask for a yes and write nothing before it. A silent write is the one thing the lens was made to prevent.
- After the yes, apply it, update the eval case of an edited skill or agent, and commit the change with a message that names the task.
- Close the task in the task tool with what was done. A refused task is closed with the reason, so the person sees the answer on the page.
The reason for the order: the person reads at the level of intent and use case, and an edit made under their eyes is one they can own.
Red flags
- When the description summarises the body, rewrite it in typed words, because the harness matches what users type.
- When the description says "and also", split the skill, because the unneeded half still loads.
- When a body line is textbook, delete it, because it adds bytes and no behaviour.
- When the purpose appears mid-body, move it to the opening, because rules are read through it.
- When a constraint says "remember to", write the hook, because prose is forgotten under pressure.
- When a skill has no eval, write the fire and scenario cases first, because an unproven skill may never load or may change nothing.
Say it in the reply
One line: kept or cut, the case run, pass or fail, the with and without delta. Name the byte size when near the cap.
04 同仓库更多 Skills
worktrunk
Use when working with git worktrees or wt (worktrunk): creating, switching, merging or removing a branch workspace, configuring wt (project or personal config, workflow hooks around switch, commit and merge, commit-message generation, hook approvals), or a wt command that failed. Triggers: make a worktree for this branch, wt merge, wt remove, configure wt, .config/wt.toml, run tests before merge, install deps when a worktree is created, wt hook, wt switch does not cd, nastav wt, wt nefunguje.
web-ladder
Use when a task needs something the internet holds: look something up, search the web, find which page answers a question, read a page, check a library's current docs, a page that needs a browser or shows a captcha. Runs one research loop: searxng search, keywords, cases, search again up to three times, Context7 for a library, Tavily when the keywords will not come, one page in a browser, the person on a wall. Triggers: look this up, search the web, find out online, read this page, check the docs, the page is blocked, captcha, najdi na webu, otevri tu stranku. A multi-round question goes to the qsm-web:web-research agent; one tool's commands are its own skill (searxng, browserbox, opensrc).
searxng
Use when running a web search through the person's own SearXNG instance with qsm-web searxng: choosing a search profile or engines, the instance, time range or language, reading its JSON, a suspended engine. Triggers: search with searxng, qsm-web searxng, search profile, niche search, academic search, IT search, vyhledavaci profil, searxng is down, which engines. The research loop around it is the web-ladder skill.
opensrc
Use when the source code of an open-source library or repository is needed on disk to read: the docs are silent, the behaviour must be checked in code, the version the project pins. Runs qsm-web opensrc get with a package spec or a repository address. Triggers: get the source of this package, clone this library, read the library's code, qsm-web opensrc, stahni zdrojak knihovny. Library docs are the Context7 skill; the research loop is the web-ladder skill.
browserbox
Use when one page needs a real browser through qsm-web browserbox: content built by script, a page that blocks plain fetching, a captcha to solve or hand to the person, a scripted sequence of clicks, a login the person is present for. Triggers: open it in a browser, the page is empty without JavaScript, captcha, take over the browser, run these steps on the page, log in to this site, browserbox. When to reach for a browser at all is the web-ladder skill.
usage
Use when the user wants a review of how they use Claude Code, or setup hands over after a first install: review my Claude Code usage, audit my setup, what does my setup cost, where did my tokens go, clean up my Claude Code, usage report, zkontroluj moje pouzivani. One walkthrough of four stages (machine, work, habits, extensions), questions after each, then one plan. A question about one topic (which hooks are slow) goes to that topic's skill; this session's tokens alone is `/qsm-usage`.