Skip to content

AAK-COMPOSE-003: A skill declares a narrower capability than its code exercises

Severity
MEDIUM
Category
Composition (composition)
Scanner
agent_audit_kit/scanners/composition.py
Auto-fixable
No.
SARIF name
CompositionUnderdeclaredCapability

What it detects

A skill's manifest declares one set of capabilities while its body or an adjacent script exercises a wider one - a network call, a shell block, a file write or a credential read the frontmatter does not admit to. This matters beyond the single skill: every composition rule builds its graph from manifests, so an under-declared component makes each chain through it look narrower than it is, and a chain that would otherwise be reported can be missed. It is reported as its own finding rather than folded into the chain rules because the fix is different - the manifest is wrong, whether or not any chain currently runs through it.

How to fix

Reconcile the manifest with the code. Either declare the capability the code actually uses, so reviewers and capability-based tooling see the real surface, or remove the code path if the narrower declaration was the intent. Prefer narrowing the code: a manifest widened to match an incidental curl grants that capability permanently.

To confirm the finding is gone, report only this rule:

agent-audit-kit scan . --rules AAK-COMPOSE-003

Limitations

This is a static pass over declared configuration. It cannot resolve tool registration that happens at runtime, so a component added from a registry fetched at start-up is invisible to it, and a chain assembled at runtime from such components will not appear here. Body capability is detected by pattern, not by parsing, so it sees a literal curl or subprocess call and not one reached through an indirection or an imported helper. It reads only files inside the skill directory. A skill that documents a capability in prose without using it can be reported where the prose contains a matching literal.

References

Deep dive

This rule is written up in Skill scanning: per-artifact pre-screen and the composition check.


All rules. This page is generated from the rule registry when the documentation is built; to change it, change the rule in agent_audit_kit/rules/builtin.py. To give the rule a hand-written write-up, add docs/rules/AAK-COMPOSE-003.md: the page then shows that text, with the registry reference appended under it.