The Agent Sees More Than Code: Metadata, Permissions, and Hooks
SkillSpector treats an AI-agent skill as more than a collection of source files. The agent may read its name, description, trigger phrases, parameter definitions, permissions, hooks, and project settings before or while deciding what to invoke. This chapter examines those agent-facing surfaces and connects them to the executable capabilities they declare or conceal, so readers can distinguish a transparency gap from evidence of malicious intent.
That distinction matters because a skill’s effective behavior is partly shaped before its code runs. A misleading name can shadow a trusted tool. A hidden instruction in a description can steer an agent’s choice. A permission declaration can make a broad capability look narrow—or can be absent when code still reads the environment or writes files. A lifecycle hook can act when an event occurs even though the behavior is stored in a settings document rather than next to the main script.
Declarations and Metadata Are Inputs to the Agent
A permission field is a claim about scope. It says, in effect, “this skill needs these capabilities.” SkillSpector’s MCP least-privilege analyzer tests that claim against observable code. It maps permission strings and Agent Skills allowed-tools values into broad capability categories such as shell access, network access, file reading, file writing, environment access, and MCP use. It then searches executable files for evidence of those capabilities.
The comparison produces four different outcomes. Underdeclared capability means code uses something not covered by the declaration. A wildcard permission such as *, all, full, or any gives a blanket answer that technically covers everything while telling the reviewer almost nothing. Missing permission scope leaves the analyzer without a useful baseline when executable code still shows sensitive capabilities. Overdeclared permission means the manifest grants a category that the analyzed code does not appear to use.
These outcomes should not be treated as equivalent accusations. Underdeclared network or environment access can be a serious transparency failure, but it may also be a documentation mistake. A wildcard can be a shortcut in a prototype, even though it removes the value of least-privilege review. An overdeclared permission can be leftover configuration or preparation for future functionality. SkillSpector gives the signals different severities and explanations because the evidence supports different judgments.
The comparison also has boundaries. It is based on patterns visible in the skill’s own files, not on a complete analysis of every library the skill imports. A capability hidden behind dynamic dispatch may be missed; a call in a branch that never executes may still be detected. Permission keywords are mapped with an English-oriented vocabulary. The result is therefore a test of declared scope against observable capability, not a proof that the skill has no other capability.
This is why allowed-tools matters for an Agent Skills manifest. It lets a tool author state the tools an agent may invoke, while the implementation can be checked for behavior that exceeds that scope. If a skill claims to be a read-only formatter but its executable content shows network or file-write capability, the mismatch deserves review even before a model is asked to interpret the author’s intent.
Metadata creates another kind of input channel.