fgts-naming-convention - SKILL.md Agent Skill

name: fgts-naming-convention description: FGTS — From General To Specific. A deterministic, scope-descending identifier system for files, variables, configs, and APIs. Makes names sortable, groupable, and self-documenting.

FGTS — From General To Specific

A deterministic, scope-descending identifier system for files, variables, configs, and APIs · v1.0

Core Principle

Every identifier is a path through a conceptual namespace, moving from the broadest context down to the most specific detail. Reading left to right is like zooming in on a map — each segment narrows the scope of the one before it.

This makes names sortable, groupable, and self-documenting without external tooling. The convention applies uniformly to filenames, variables, config keys, API routes, and database fields.

Segment Anatomy

<domain>_<system>_<entity>_<attribute>_<qualifier>

Position	Level	Role	Examples
1	Domain	Top-level context	`net` `auth` `db` `ui` `cfg`
2	System	Subsystem / module	`flow` `session` `query` `form` `cache`
3	Entity	Object / resource	`iface` `user` `table` `input` `entry`
4	Attribute	Property / metric	`bytes` `count` `ts` `id` `name` `rate`
5	Qualifier	Direction / state / variant	`in` `out` `prev` `max` `raw` `err`

Canonical example:

net_flow_iface_bytes_in
│   │    │     │     └─ qualifier : inbound direction
│   │    │     └─────── attribute : byte count
│   │    └───────────── entity    : network interface
│   └────────────────── system    : NetFlow pipeline
└────────────────────── domain    : network monitoring

Segments are separated by _ (snake_case). Use - (kebab-case) for filenames and URLs. Omit trailing segments when specificity is unambiguous in context.

Rules

Left-to-right specificity is mandatory. Never place a narrower segment before a broader one. auth_session_user_id is valid; id_user_session_auth is not.
All lowercase, no spaces. Snake_case for code identifiers; kebab-case for file paths and URLs. Mixed case within segments is forbidden.
Use abbreviations consistently. Establish a project-level glossary (e.g. ts = timestamp, cnt = count, cfg = config). Never mix abbreviated and full forms of the same word.
Omit obvious segments. Inside the auth module, session_id is sufficient — prepending auth_ is redundant. Apply the innermost-scope rule.
No verbs in data names. Verbs belong in function/method names. Data identifiers describe what a thing is, not what you do with it. db_query_result_rows not db_get_query_rows.
Qualifiers are the last resort. Only add a Level 5 qualifier when the attribute is genuinely ambiguous without it. bytes_in vs bytes_out is valid. count_final is a smell.
Plural only at the entity level. net_flow_ifaces_count — the entity (ifaces) is plural because it's a collection. Attributes and qualifiers stay singular.

Examples by Context

Context	FGTS Identifier	Meaning
Variable	`net_flow_iface_bytes_in`	Inbound byte count for a specific interface in the NetFlow pipeline
Config key	`db_cache_ttl_sec`	TTL in seconds for the database cache layer
Filename	`auth-session-token-refresh.py`	Script for refreshing session tokens in the auth subsystem
API route	`/net/flow/iface/{id}/bytes`	REST endpoint exposing byte metrics for an interface
DB column	`auth_session_user_id`	FK to user within the session table of the auth schema
Metric	`net_flow_iface_pkt_drop_rate`	Packet drop rate per interface in the flow domain
CSS variable	`--ui-form-input-border-focus`	Border color token for focused state of form inputs
Env var	`DB_REPLICA_HOST_PRIMARY`	Hostname of the primary replica (SCREAMING_SNAKE)

Good vs. Bad

✗ Violations

getFlowBytesIn          # verb prefix + camelCase — wrong casing, wrong order
in_bytes_iface_net      # reversed specificity — qualifier before domain
iface_bytes             # missing domain context — collides across systems
netFlowIfaceByteIn      # camelCase — reserved for method/function names

✓ Correct

net_flow_iface_bytes_in       # all five levels, left-to-right, snake_case
net_flow_iface_bytes_out      # parallel structure — differs only at qualifier
net_flow_iface_pkt_cnt        # abbreviation used consistently per glossary
flow_iface_bytes_in           # domain omitted — valid inside a net-scoped module
net-flow-iface-report.md      # kebab-case for filename; same hierarchy

Starter Abbreviation Glossary

Abbrev	Full form	Abbrev	Full form
`ts`	timestamp	`cnt`	count
`cfg`	config	`pkt`	packet
`iface`	interface	`err`	error
`sec`	seconds	`ms`	milliseconds
`max` / `min`	maximum / minimum	`prev` / `cur`	previous / current
`req` / `res`	request / response	`raw`	unprocessed value

FGTS Naming Convention · From General To Specific · v1.0 · 2026