How to Organize a Project Root Level Like Nutlope/hallmark: Best Practices Explained

The best way to organize a project root level is to separate runtime assets, skill definitions, and documentation into single-purpose directories while keeping only project-wide descriptor files at the root.

The Hallmark repository by Nutlope demonstrates a clean, purpose-driven layout that makes skills easy to install, version, and extend. This article breaks down the organizational patterns used in the Nutlope/hallmark codebase so you can apply them to your own projects.

Core Principle: Single-Purpose Directories

Hallmark enforces strict separation between concerns. Each top-level folder has exactly one job:

Directory	Purpose	Example Path
skills/	Skill definition and reference materials	skills/hallmark/SKILL.md
site/	Static website files for demos	site/index.html
docs/	Human-readable guides and screenshots	docs/recipes.md

This division prevents accidental edits to skill logic when working on the demo site. It also lets contributors locate guides quickly without wading through source code.

Minimal Root Files

Keep your repository root lean. Only include files that describe the project as a whole:

• README.md — high-level description and installation instructions
• package.json — package metadata and entry points
• LICENSE — reuse rights (MIT in Hallmark's case)
• .gitignore — exclusions for generated files

Avoid placing component-level code or large data files at the root. Nest them in the relevant subfolder instead.

Explicit Entry Points in package.json

The package.json in Hallmark serves as the authoritative project descriptor. Key fields include:

{
  "name": "hallmark",
  "skill": "skills/hallmark/SKILL.md",
  "files": [
    "skills"
  ],
  "scripts": {
    "serve": "python3 -m http.server --directory site 4173"
  }
}

The "skill" field declares the entry point explicitly, enabling installers like npx skills add nutlope/hallmark to locate the correct file without ambiguity. The "files" array limits what npm publishes, keeping distributions lean.

Versioned and Immutable References

All reference documentation lives under skills/hallmark/references/. These Markdown files are version-controlled and never edited at runtime.

For example, macrostructure definitions reside in skills/hallmark/references/macrostructures.md. The skill reads these at execution time, guaranteeing reproducible behavior across environments.

Consistent Naming Conventions

Hallmark uses predictable patterns throughout:

• Folder names: kebab-case (site, skills, docs)
• Rule files: start with the verb (audit.md, redesign.md)
• Reference files: descriptive nouns (macrostructures.md)

This makes files discoverable via tab completion and reduces cognitive load for new contributors.

Static Assets Colocation

Images, favicons, and screenshots sit inside site/ or docs/screenshots/. This keeps the asset pipeline simple and prevents cross-contamination with the skill's Markdown resources.

Practical Examples

Adding a New Reference File

mkdir -p skills/hallmark/references/macrostructures
cat > skills/hallmark/references/macrostructures/custom-hero.md <<'EOF'

# Custom Hero Macrostructure

...
EOF

The new file becomes automatically discoverable because the skill loads all macrostructure references on demand from the references/ folder.

Updating package.json for New Assets

{
  "name": "hallmark",
  "version": "1.1.0",
  "files": [
    "skills",
    "site/assets"
  ]
}

Adding "site/assets" ensures those assets bundle when publishing.

Adding Documentation Without Bloat

touch docs/new-tutorial.md

Because docs/ is excluded from the npm "files" list, tutorials stay repository-local without increasing distributed package size.

Safety-First .gitignore

Hallmark's .gitignore excludes generated files and node_modules, keeping the repository lightweight and preventing accidental commits of large binaries.

Summary

• Separate concerns with single-purpose directories (skills/, site/, docs/)
• Keep root minimal with only project-wide descriptors
• Declare entry points explicitly via package.json fields
• Version references immutably under skills/<name>/references/
• Use consistent naming (kebab-case folders, verb-first rule files)
• Control distribution size with the "files" array in package.json

Frequently Asked Questions

What files should go at the root versus in subdirectories?

Only project-wide descriptors belong at the root: README.md, package.json, LICENSE, and .gitignore. Everything else—code, assets, documentation—should nest in its appropriate subdirectory. This prevents root clutter and makes project structure scannable at a glance.

How does the "skill" field in package.json work?

The "skill" field points to the main skill definition file, typically a Markdown file like skills/hallmark/SKILL.md. Installers read this field to locate the entry point without hardcoded assumptions. This pattern enables dynamic skill discovery and installation across the ecosystem.

Why separate site/ from docs/ if both contain HTML and images?

site/ contains the live demo—runnable, browsable assets served by python3 -m http.server. docs/ contains human-oriented guides and screenshots that explain how to use the skill. Separation prevents demo deployment from accidentally publishing draft documentation, and keeps contributor guides separate from user-facing demos.

Should I include documentation in npm published files?

Typically no. Hallmark excludes docs/ from its "files" array, keeping the npm package focused on runtime essentials. Documentation remains available in the repository for contributors and on GitHub for readers, without bloating installations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}