从威胁模型到框架：弥合 Agent Skill 安全的真正缺口

A couple of weeks ago I wrote about the risk hiding inside AI Agent Skills, the small instruction folders that Claude, GitHub Copilot, and other agents now install like packages, and the fake malicious skill I built to prove that risk was real (full piece here if you want the background). That post was the problem statement, a threat model, and a proof of concept.

This post is the framework. Since then I've actually built the thing out, agent-skills-guard, and along the way I found the real edges of what it can and can't do. Here's each open challenge, and exactly what in the framework answers it now, tested with real output rather than claims. Challenge 1: the trap can hide in the field that decides whether the skill even runs

A Skill's description isn't just a label. It's the one piece of text an agent reads for every installed skill, every session, before it decides anything else. If an attacker can slip an instruction in there, the agent never needs to open a script or a reference file at all. It just needs to glance at the catalog.

So I built a test case where the entire trap lives in the description field and nowhere else:

No body text, no scripts, nothing. Ran it:

It caught both. The framework reads the whole SKILL.md file as one block of text, frontmatter included, so the description field gets exactly the same scrutiny as the body. The part deciding whether a skill fires is still just text, and text is exactly what a static scanner reads.

Worth being honest about the edge this doesn't cover: a description crafted to make the skill over-trigger for unrelated tasks, with persuasive wording but no hidden instruction at all. That's closer to SEO manipulation than prompt injection, and nothing here looks for it yet. Challenge 2: nothing notices when a skill changes after you've already trusted it

This is the gap I don't have a full answer for yet, and I'd rather say so than pretend otherwise. Right now, the framework scans a skill at a single point in time. A clean report today says nothing about tomorrow. A skill maintained by someone else can update after you've already pulled it and approved it, and nothing here would notice.

The direction I'm building toward: hash the contents of a skill directory at scan time, store that alongside your approval, and add a --check-drift mode that re-hashes on demand and flags anything that changed since. Not code yet. Naming it here on purpose, so it doesn't quietly fall off the roadmap. Challenge 3: a fixed word list goes stale the moment you ship it

This showed up the moment I tried to extend my own tool. The first version had every detection pattern hardcoded directly in the Python file. Adding one new pattern meant editing code, which meant almost nobody ever would.

So detection rules now live in a plain rules.json file, separate from the code entirely. Here's what adding exactly one line buys you. Take a skill that posts to a Slack webhook URL hardcoded in its script, a very real and very leaky pattern, since credentials sit right inside the URL itself:

Before, using the rules that shipped originally:

It noticed a network call, but had no idea the URL itself was a leaked secret. After adding one line to rules.json:

Same skill, same scan:

No code touched, and the finding jumped from "noticed something" to "here's specifically why this is bad." That example was useful enough that I've since added it, along with the Discord webhook equivalent, to the rules file that ships with the framework. This is the real answer to "keyword lists go stale": don't solve it with smarter code, solve it by making the list something anyone can extend in thirty seconds. Challenge 4: a scanner nobody can quiet down is a scanner people stop running

This one came from watching my own false positive happen. An earlier test flagged the word "silently" in a sentence explicitly saying a function does not do something silently. Correct catch by the letter of the rule, wrong in context, and there was no way to tell the framework "yes, I saw this, it's fine."

That's a real adoption killer. The fix wasn't a smarter pattern, false positives are unavoidable in anything pattern-based. The fix was giving a reviewed finding somewhere to go that isn't oblivion:

That finding still shows up, downgraded and labeled, reason attached:

Nothing vanishes silently. Anyone reviewing the report later can still see exactly what got waved through and why. That distinction, downgrade and label versus hide entirely, is doing a lot of work for how much I'd trust this framework if someone else were the one running it. Where the framework stands

Two gaps closed with actual evidence, one gap named honestly as still open, and one design habit (rules in a file, not buried in code) fixed because it was slowing down the framework as much as anyone using it. That's the real state of things, not a claim that everything from the original threat model is solved.

If there's a gap in here that still wouldn't catch something obvious to you, I'd rather hear it now, in a comment, than find out later.

Repo: https://github.com/karthidec/agent-skills-guard