Respect flat skill layouts — subdirectories are optional per spec

[philoserf]

Problem

The Agent Skills spec treats scripts/, references/, and assets/ as optional organizational directories. A valid skill can be completely flat:

my-skill/
├── SKILL.md
├── guide.md
├── extract.py
└── template.txt

The validator currently penalizes this layout in several ways:

1. Root-level file warnings (structure/checks.go): Any file at root besides SKILL.md triggers an "unexpected file" warning, nudging authors toward subdirectories they may not need.

2. Unknown directory warnings (structure/checks.go): Non-standard directories at root generate warnings suggesting they should be references/ or assets/, even though custom directory names are not spec violations.

3. Orphan detection blind spot (structure/orphans.go): Orphan checking only inventories files inside references/, scripts/, and assets/. Root-level support files are invisible to orphan detection — unreferenced files at root are never flagged.

4. "Non-standard" token accounting (structure/tokens.go): Files outside the three recognized directories are bucketed as "non-standard" with separate aggregate limits (25k soft / 100k hard). A flat skill with guide.md at root gets stricter treatment than the same file inside references/.

5. Skill ratio penalty (structure/validate.go): If "non-standard" tokens exceed 10x "standard" tokens, the skill is flagged as possibly misconfigured. A flat skill with substantial reference material would hit this even though the layout is valid.

Proposed Changes

Treat recognized file types at root as first-class

• .md files at root (beyond SKILL.md) should be treated equivalently to files in references/
• .py, .sh, .js, .ts files at root should be treated equivalently to files in scripts/
• Other files at root should be treated equivalently to files in assets/
• Remove or downgrade the "unexpected file at root" warnings for files that have recognized extensions

Extend orphan detection to root-level files

• Include root-level support files in the orphan inventory
• Apply the same BFS reachability check from SKILL.md to these files

Unify token accounting

• Count root-level support files under the same limits as their subdirectory equivalents (e.g., a root guide.md counts toward reference token limits, not "non-standard" limits)
• Adjust checkSkillRatio() to not penalize flat layouts

Preserve hints without penalizing

• It's still useful to inform authors that subdirectories exist for organization, but this should be Info-level, not Warning-level, and only when there are enough files that organization would genuinely help (e.g., 5+ support files at root)

Context

The spec explicitly says:

A skill is a directory containing at minimum a SKILL.md file

and presents the three subdirectories under "Optional directories." The validator should validate the spec, not enforce a preference for structured layouts over flat ones.

[dacharyc]

Hey @philoserf - thanks for creating the issue. I understand your rationale, but these were intentional design decisions. I detailed some of the driving factors here: Structure Validation/Extraneous File Detection.

It looks like the official Anthropic skill-creator skill that I'm citing in the README has had its language changed in commit 3d59511518591fa82e6cfcf0438d68dd5dad3e76, but the old guidance was pretty clear about using the structured directories for supplemental material.

Since the spec doesn't provide any guidance for how agent platforms should implement file access patterns, I indexed on Anthropic's own guidance in the skill-creator skill as the best way to avoid context window bloat and file discovery issues. Until I have time to do some testing around how the various platforms implement skill discovery, context window management, and file access, I'm planning to stick with this more conservative approach.

I'm happy to keep the issue open for comments, though, and am open to revisit once there's more empirical evidence about implementations to help guide changes.

[philoserf]

Very well. Inflexibility makes the tool less useful in these early days. Tools that enforce one way—and a way the holds hidden worldview—are unfortunate.

[dacharyc]

Heard and understood, Mark - sorry to disappoint. Now that I've got at least one data point where this is negatively impacting someone using the tool, I'll try to prioritize exploring implementation details across platforms in the next few weeks so I can gather data for or against this change. If you have any inclination to explore this yourself and share any data you find, that could help speed things up.

I'm mainly interested in understanding how agent platforms implement Skill access and loading, related file discovery, and how that impacts context window usage. If implementation details across platforms mean that flat skill structures are a non-issue, I'm happy to revisit this. I just haven't had time to do that discovery myself yet.

[philoserf]

I will learn to surrender to community standards. We will watch them develop. Thank you for the tool.

[dacharyc]

Hey @philoserf - another request came in where I think an optional flag could enable the more permissive behavior requested, and I'm wondering how you would feel about that approach for flat skill layouts? i.e. - if I were to implement an --accept-flat-layouts flag for folks who want this functionality, would that solve your use case? This could preserve the existing behavior for folks like me who want to ensure maximum spec compliance, but could also enable validation for folks like you who would prefer to have a flat layout not be penalized across the dimensions you identified here.

[dacharyc]

Hey @philoserf - just noting I have merged and released support for flat skill layouts in v1.3.0 with the optional --allow-flat-layouts flag. This seemed to work in my local testing; hopefully it serves your case. Let me know if you run into any issues with the implementation and I'm happy to add any fixups.

[philoserf]

Looks good. I have a very large collection of skills as offered in pull requests to Anthropic at https://github.com/anthropics/skills, some of which are unlovely. Ran over that collection, and the allow-flat-layouts performed as expected.