agentskill-structure

Skill directories should only contain recognized subdirectories (stricter than spec)

Severity	warning (disabled)
Autofix	-
Since	v0.1.0
Repo Types	agent-plugin, agentskills, antigravity-plugin, codex-marketplace, codex-plugin, dot-claude, grok-marketplace, grok-plugin, marketplace, single-plugin
Category	agentskills.io

Why

The formal Agent Skills specification permits arbitrary directories. This disabled-by-default rule is an optional packaging policy for repositories that want to limit skill-root directories to a configured allowlist. Its defaults cover common Agent Skills directories and the evaluation-guide evals/ convention. OpenAI's agents/ host-metadata directory is accepted separately; it is not repository-authored package content governed by this policy.

Examples

Bad:

my-skill/
  SKILL.md
  helpers/       # not allowed by this project's configured policy
  test-data/     # not allowed by this project's configured policy

Good:

my-skill/
  SKILL.md
  evals/
  references/

How to fix

Move files into one of the configured directories, add the intentional directory to allowed_dirs, or disable this opt-in rule.

Configuration

rules:
  agentskill-structure:
    enabled: false  # true | false | auto
    severity: warning

Parameter	Description	Default
allowed_dirs	Directory names allowed in the skill root	["assets", "evals", "references", "scripts"]

Run skillsaw explain agentskill-structure to see this documentation and the rule's effective configuration in your terminal.