<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# 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](agentskills.md) |

## 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

```yaml
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.*