documentation-layout - generalize examples carve-out and require flat skill folders #80

New issue

Closed

opened 2026-05-28 01:21:39 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-05-28 01:21:39 +00:00

Owner

Problem

Two extensions to documentation-layout (agentic_os/check_documentation_layout.py):

Rule 1 — generalize the examples/ carve-out. Today is_example_readme() exempts only examples/<name>/README.md and examples/<name>/<x>/README.md at the repo root. Idiomatic Go/Rust examples can be nested deeper and may include .md files beyond README.md. Generalize: any path containing a examples/ segment at any depth may contain .md files of any name.

Rule 2 — skills must be flat (new). Inside a skill folder (.agents/skills/<skill>/, .claude/skills/<skill>/, skills/<skill>/), no subdirectories. All files (SKILL.md, references, anything else) must live as direct children, beside SKILL.md. The current convention of <skill>/references/<file>.md becomes a violation; references move up to <skill>/<file>.md.

Why

Rule 1 unblocks legitimate examples trees that the narrow current carve-out can't represent. Rule 2 mirrors the existing docs/ flatness rule and makes skill contents directly greppable / loader-discoverable without one more layer of directory walk.

Scope of this issue

Code change in agentic_os/check_documentation_layout.py only:

Replace is_example_readme() with is_under_examples() (any depth, any .md filename).
Add check_skill_flatness() that walks each SKILL_PATHS root and flags any directory found under a skill folder.
Wire it into main().

Out of scope

Fixing the resulting violations in agentic-os's own skills (the references/ directories). The hook is not enabled on this repo yet; existing skills will break when it is. Separate sweep, separate issue.
Tier policy for size caps. Separate issue.
Rolling the change out to consumers via apply-agentic-os-hooks.py. Separate issue.

Acceptance

is_under_examples(Path("examples/foo/bar/baz.md")) returns True.
A directory under .agents/skills/<skill>/ produces a violation naming that path and pointing at "skill folders must be flat".
Existing tests in agentic-os still pass; new tests cover both rules.

**Problem** Two extensions to `documentation-layout` (`agentic_os/check_documentation_layout.py`): **Rule 1 — generalize the `examples/` carve-out.** Today `is_example_readme()` exempts only `examples/<name>/README.md` and `examples/<name>/<x>/README.md` at the repo root. Idiomatic Go/Rust examples can be nested deeper and may include `.md` files beyond `README.md`. Generalize: any path containing a `examples/` segment at any depth may contain `.md` files of any name. **Rule 2 — skills must be flat (new).** Inside a skill folder (`.agents/skills/<skill>/`, `.claude/skills/<skill>/`, `skills/<skill>/`), no subdirectories. All files (`SKILL.md`, references, anything else) must live as direct children, beside `SKILL.md`. The current convention of `<skill>/references/<file>.md` becomes a violation; references move up to `<skill>/<file>.md`. **Why** Rule 1 unblocks legitimate examples trees that the narrow current carve-out can't represent. Rule 2 mirrors the existing `docs/` flatness rule and makes skill contents directly greppable / loader-discoverable without one more layer of directory walk. **Scope of this issue** Code change in `agentic_os/check_documentation_layout.py` only: - Replace `is_example_readme()` with `is_under_examples()` (any depth, any `.md` filename). - Add `check_skill_flatness()` that walks each `SKILL_PATHS` root and flags any directory found under a skill folder. - Wire it into `main()`. **Out of scope** - Fixing the resulting violations in `agentic-os`'s own skills (the `references/` directories). The hook is not enabled on this repo yet; existing skills will break when it is. Separate sweep, separate issue. - Tier policy for size caps. Separate issue. - Rolling the change out to consumers via `apply-agentic-os-hooks.py`. Separate issue. **Acceptance** - `is_under_examples(Path("examples/foo/bar/baz.md"))` returns `True`. - A directory under `.agents/skills/<skill>/` produces a violation naming that path and pointing at "skill folders must be flat". - Existing tests in agentic-os still pass; new tests cover both rules.

coilysiren referenced this issue from a commit

2026-05-28 01:23:52 +00:00

feat(documentation-layout): generalize examples carve-out, require flat skill folders

coilysiren closed this issue

2026-05-28 01:23:52 +00:00

coilysiren referenced this issue

2026-05-28 01:29:10 +00:00

apply documentation-layout to agentic-os itself - flatten skills, fix size violations, wire the hook #81

coilysiren referenced this issue from a commit

2026-05-28 01:33:05 +00:00

docs(AGENTS): replace hardcoded size caps with pointer references to the upstream validator