File Headers Agent Skill

File Headers — Copyright Comment + File Overview

Every applicable source file in this repository starts with a header comment

containing a file overview and the exact author line:

@author Son Nguyen <[email protected]>

The name and email must be exactly as above — no variations, no substitutions,

no other names. This applies to every coding agent working in this repo

(Claude Code, Codex, or any other tool): when you create a new applicable

file, write the header first; when you update an existing applicable file

that is missing the header, add it as part of the same change.

Applicable files

| Included | Excluded |

| -------- | -------- |

| *.js, *.ts, *.tsx, *.cjs, *.mjs | anything under node_modules/, dist/, build/, data/ |

| *.py, *.sh | vendored/minified files (*.min.js, wiki/mermaid.min.js) |

| *.css | generated files (wiki/i18n-content.js — carries its own AUTO-GENERATED banner) |

| | snapshots (__snapshots__/), lockfiles, JSON/YAML/Markdown |

Header formats by file type

JS / TS / TSX — server & scripts style (overview inline in @file):

/**
 * @file One-to-few-sentence overview of what this file does and why it
 * exists. Mention the key contracts or invariants the file owns.
 * @author Son Nguyen <[email protected]>
 */

JS / TS / TSX — client style (@file name + @description overview), used

under client/src/:

/**
 * @file ComponentName.tsx
 * @description What the component/module renders or provides and how it fits
 * into the app.
 * @author Son Nguyen <[email protected]>
 */

CSS (same block-comment shape as client/src/index.css):

/**
 * @file file.css
 * @description What these styles cover.
 * @author Son Nguyen <[email protected]>
 */

Shell (# block right after the shebang; existing overview comments count —

just make sure the @author line is in the block):

#!/usr/bin/env bash
# script-name.sh — what the script does, one to few lines.
# @author Son Nguyen <[email protected]>

Python (inside the module docstring):

"""
module.py — what the module does.

@author Son Nguyen <[email protected]>
"""

Rules

• New file → header first. Any applicable file you create starts with the

header before any code (after the shebang for scripts).

• Touched file missing header → add it. If you edit a file that lacks the

header, add one in the same commit. Write a real overview — describe what

the file actually does; never a placeholder like "TODO" or "utility file".

• Exact author line. @author Son Nguyen <[email protected]> —

byte-exact, in every file type (shell and Python use it inside # / docstring

comments).

• Don't churn existing headers. If a file already has a compliant header,

leave it alone unless the file's purpose changed (then update the overview).

• Overviews must stay truthful. When an edit changes what a file does,

update its @file/@description overview in the same change.

Audit

Run the bundled checker to list any applicable file missing the header:

bash .claude/skills/file-headers/scripts/check-headers.sh

Exit code 0 = fully compliant; 1 = the printed files are missing headers.

Run it before finishing any change-set that adds files, and during reviews.

On every pull request, GitHub Actions runs

.claude/skills/file-headers/scripts/check-headers-pr.sh against only the

files changed in the PR diff (added, copied, renamed, or modified). Test locally

before pushing:

bash .claude/skills/file-headers/scripts/check-headers-pr.sh origin/master HEAD