Skills: the gate

Read this before changing skill_gate.go, skill_scanner.go, skill_text_view.go, skill_quality.go, or a way a skill reaches GoClaw.

A skill's text goes into the system prompt, ahead of the history, so it speaks with the agent's own authority. The gate is the one security check for a skill, however it got here. Each way in is an adapter over it, as a provider is over the agent loop, and skill_gate_conformance_test.go runs one set of skills through all of them.

Every skill passes the last row, whichever row it came in by: it is the backstop for a file that changed after it was checked. It drops a skill before selection, so a blocked skill wins no place in FilterSkillsFor or keepSessionSkills, and one that turned bad mid-session is gone from the next turn. LoadSkills is the full list, for the admin's views (Skills page, skills list, skills scan); nothing that builds a prompt may read it.

The verdict

SkillVerdict is safe, caution or block, and it is not the quality score:

• Any critical finding blocks. Warnings, or a scan that could not read everything, are caution.
• The score never makes up for a finding. A skill can score 90 and be blocked.
• A model raises a verdict and never lowers one (SkillSecurity.raise). A skill the scanner blocks is not sent to a model at all.
• caution loads. A save stops on it only when no model reviewed the skill (needsAcceptance).
• A model's failure is not a pass. noteReview tells a refusal (errModelDeclined, a finding of its own) from a cut answer (errSkillReviewCut) from a model that could not be reached. A clean skill saves on the static score, as an install with no model always has; one with warnings waits for an admin.

What the scanner reads

• skillTextView holds each line as written, normalized (NFKC, invisible characters out, Unicode tag characters read as the ASCII they spell, Cyrillic and Greek lookalikes folded to Latin), and the whole text as one line. A finding always names the line and shows the text the author wrote. The normalized view makes Mongolian text nonsense: a rule for Cyrillic text takes rawText.
• A rule that spans lines takes spansLines, and needs a bounded pattern: .* would read the whole skill as one sentence.
• negatable rules pass over a prohibition (prohibited): "never run rm -rf /". The grammar is narrow on purpose, a negation that governs the match directly with only scanBridgeWords between, and none in a clause with "unless". A looser one is what an attacker would write to.
• ScanSkillDir reads every file, and what it does not read goes in Skipped with the reason. A skipped file makes the scan partial, and a partial scan is never safe. Only inertExts, .git and __pycache__ are left out silently.
• gatedSkill reads SkillEntry.Content, the text the agent reads with references/ inlined, memoized by hash. It runs no model: a turn cannot wait for one.

Before tightening a rule to critical, remember it is enforced at load. Run it over skills-registry/ and the built-in skills (TestBuiltinSkillsPassTheGate fails on a built-in), and prefer warn where a real skill could say the same thing.

An acceptance

skills.accepted in config.yaml maps a skill's name to the hash of the text an admin read (AcceptSkill). It is in config.yaml because no tool of the agent writes there. The hash (skillContentHash) covers the text, the description and the tags: any change voids it, as it does a plugin item's approval. The dashboard sends the hash the page showed, so nothing changed meanwhile is accepted unseen. skills.gate: warn turns the block at load into a log line, for a first rollout. SkillSecurity.Withheld is what all of it comes to: models do not get this skill.