agentleFS
Sign inStart free
frostneyfrostney/pascal-mcp-sdk/.agents/skills/project-structure/SKILL.md

project-structure

Skill2 starsChanged 3 months agoMITView on GitHub

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.

We split this skill into the rules it gives an agent

7 rules. 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never maintain divergent copies.

    line 53
  2. Distinctive:

    Keep the root AGENTS.md lightweight: briefly identify the repository, then spend its context on non-obvious gotchas, exact commands, hard …

    line 55
  3. Very specific:

    Add nested <area>/AGENTS.md only where rules differ.

    line 60
  4. Very specific:

    If curated skills are provisioned, .agents/skills/ and skills-lock.json are generated by the skills tool, never hand-edited.

    line 64
  5. Distinctive:

    Read references/documentation.md when creating or restructuring README, docs, governance, agent files, or a multi-area repo.

    line 70
  6. Very specific:

    Read references/tooling.md when installing hooks, scripts, changelog generation, markdown/link/duplication checks, or architectural-drift …

    line 72
  7. Distinctive:

    No unrelated structural migration was introduced.

    line 81

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. 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/, or tools/.
  • 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 symlink to it, or contains only an include plus genuine Claude-specific additions when symlinks are unavailable. Never maintain divergent copies.

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free