project-structure
Applies the user's language-agnostic repository layout, documentation, governance, hook, test, agent-file, and changelog conventions. Use when scaffolding or restructuring a repo, writing AGENTS.md or docs, or laying out folders.
How do I install this agent skill?
npx skills add https://github.com/frostney/known-good-route --skill project-structureIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides guidelines and templates for repository organization, documentation, and governance. It defines naming conventions for core directories and specifies the contents of architectural, agent-specific, and governance files. No security risks, malicious behaviors, or executable code were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Project structure
Apply only the roles and documents needed by the requested work. Preserve valid project conventions; surface a material restructuring choice before making it. Language and stack skills own language-specific commands and config.
Core layout
Name these roles according to the ecosystem:
- Root: user-facing
README.md, manifest, one canonical lockfile, agent context, optional contribution rules, and governance files. - Source: one conventional source root, organized by domain or namespace.
- Tests: unit tests co-located with source; end-to-end suites in one top-level project-owned location; add layer-specific tests only for delivered or regression-prone layers.
docs/: architecture, quick start, tooling, code style, and deployment.- Scripts: one-off automation in
scripts/,bin/, ortools/. - Generated output: one ignored build/output location.
- Optional: generator templates, static assets, and provisioned agent skills.
Tests must catch meaningful regressions. End-to-end coverage is the primary system-level net; unit tests cover public module behavior without duplicating the same assertion.
Governance
Projects on this style keep these canonical root files:
VISION.md: durable product and technical direction, including exclusions.DEFINITION_OF_READY.md: hard gate before implementation.DEFINITION_OF_DONE.md: hard gate before a change is called shippable.
In a multi-area repo, the nearest area-specific file wins. Link between governance, agent, contributor, and project docs instead of duplicating policy. Flag a missing governance file when a workflow requires it; do not invent a substitute.
Agent context
AGENTS.md is canonical. CLAUDE.md is a regular file whose first line is
@AGENTS.md, followed only by genuine Claude-specific additions. It covers
Claude Code sessions that cannot read AGENTS.md directly, and an imported
AGENTS.md is never loaded twice. Never a copy, and never a symlink: Git checks
a symlink out as a one-line text file on Windows without core.symlinks, and
Claude Code's Edit and Write tools refuse to write through one. Replace a
symlinked or copied CLAUDE.md with the import, and update anything that relied
on the link.
Keep the root AGENTS.md lightweight: briefly identify the repository, then
spend its context on non-obvious gotchas, exact commands, hard constraints, and
safety boundaries. Do not restate a file tree or conventions evident from the
repository.
Add nested <area>/AGENTS.md only where rules differ; the root points to each
area. Use CONTRIBUTING.md for authoritative human merge requirements and link
to it rather than repeating them.
If curated skills are provisioned, .agents/skills/ and skills-lock.json are
generated by the skills tool, never hand-edited. Symlink .claude/skills to
.agents/skills.
Situational references
- Read references/documentation.md when creating or restructuring README, docs, governance, agent files, or a multi-area repo.
- Read references/tooling.md when installing hooks, scripts, changelog generation, markdown/link/duplication checks, or architectural-drift enforcement.
Completion
- The repository's declared verification gate passes.
- Documentation changed by the work is current and has one authoritative home.
- Generated files were changed through their owner tool.
- No unrelated structural migration was introduced.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/frostney/known-good-route/project-structure">View project-structure on skillZs</a>