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

> Learn best practices for organizing your project root level like Nutlope/hallmark. Separate assets, definitions, and docs into distinct directories for a cleaner structure.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-08-18

---

**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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| `site/` | Static website files for demos | [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) |
| `docs/` | Human-readable guides and screenshots | [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/README.md) — high-level description and installation instructions
- [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) in Hallmark serves as the authoritative project descriptor. Key fields include:

```json
{
  "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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/audit.md), [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md))
- **Reference files**: descriptive nouns ([`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/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

```bash
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

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

```

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

### Adding Documentation Without Bloat

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/README.md), [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.