follow-conventions
Skill4 starsChanged 3 days agoApache-2.0View on GitHub
Coding conventions for Pnyx code that AGENTS.md and ESLint do not already state, such as when to split a file, early-return guards, named constants, plain named steps, HydraError failures, one decision in one place, behavior-preserving refactors and installed-version APIs. Read before writing or reviewing Pnyx code.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- audit-testsSkill
- deslopSkill
- review-codeSkill
- write-ci-workflowSkill
- write-front-endSkill
- write-pull-requestSkill
- write-skillSkill
- inscribeSkill
- pnyx-arrange-columnsSkill
- pnyx-cliSkill
- pnyx-firstmate-as-hydraSkill
- pnyx-manage-workersSkill
- pnyx-orchestrateSkill
- pnyx-report-progressSkill
- pnyx-set-upSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Put guard clauses first: check invalid cases at the top, return or throw, and let the main flow read after them without extra indentation.
- Very specific: line 22
Write conditions in their positive form.
- Distinctive: line 23
Delete dead branches: an arm an earlier guard handled, a check on an already narrowed value, a fallback no caller can reach.
- Very specific: line 27
Import a file in the same folder as ./file.ts.
- Very specific: line 28
Write the file's real extension in the import: .ts under src/, .ts or .tsx under web/src/.
- Distinctive: line 38
Write a rule the code checks in more than one place once, as a named helper every site imports.
- Distinctive: line 40
Never drop an error to make code tidy.
- Distinctive: line 49
Write library and Node calls from the installed version's types, not from memory, and avoid deprecated APIs.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Follow conventions
AGENTS.md holds the layout, design rules and the one-object-parameter rule, and pnpm run lint enforces formatting. This skill adds the rest. Cleaning up code that drifted from these rules is deslop.
Files and concerns
- Split a file when it holds unrelated concerns, so each part has one clear job and a reader can find it by name. Keep closely related code together, even when that mixes a few kinds of work; a split that scatters one idea across files is harder to follow than one longer file.
- A very large file outside the provider adapters is a signal to look for unrelated concerns, not a limit to enforce.
- Provider adapters (
src/workers/claude.ts,src/workers/codex.ts) hold their provider's specific code, as Provider boundaries describes, and may grow larger than other files.
Control flow
- Clear beats short. Fewer lines is not the goal; a new reader should follow the code on first read. Write three plain named steps instead of one chained line, and avoid a clever trick, a long call chain or a nested condition. Code that needs a comment to say what it does needs a clearer shape instead.
- Reuse before writing: search for an existing helper, component or platform feature first, and keep each rule or state in one place.
- Put guard clauses first: check invalid cases at the top,
returnorthrow, and let the main flow read after them without extra indentation. - In new code, avoid nesting ternaries: a second level of branching reads better as a small named helper.
- Write conditions in their positive form. A
const skip = !knownflag feeding an inverted branch makes the reader flip it twice. - Delete dead branches: an arm an earlier guard handled, a check on an already narrowed value, a fallback no caller can reach.
Imports
- Import a file in the same folder as
./file.ts. Import every other file through thepackage.jsonaliases, even inside the same feature:#tasks/model.tsforsrc/tasks/model.tsand#web-shared/ui/icon.tsxforweb/src/shared/ui/icon.tsx. ESLint rejects../. - Write the file's real extension in the import:
.tsundersrc/,.tsor.tsxunderweb/src/.
Names and values
- Give a value with meaning (a timeout, a limit, a retry count, a cutoff) a named constant, declared after the imports, and share it between every site that uses it. Structural literals such as a
0index need no name. - Name each meaningful intermediate value. Avoid vague names (
tmp,data,res,obj) and long&&or||chains inside one condition; name the checks instead. review-code lists the shorthand new code never uses, such as conditional spreads and??=. - Pass a function directly when a callback only forwards its argument:
.map(toRow), not.map(card => toRow(card)).
Decisions and errors
- Write a rule the code checks in more than one place once, as a named helper every site imports.
- Throw a
HydraErrorwith its code at the failure site;guard()turns it into the CLI's structured error. Acatchthat doesn't recognize an error rethrows it. - Never drop an error to make code tidy. A deliberate fire-and-forget says in a short comment why losing the failure is safe.
Provider boundaries
- Provider-specific usage formats and names belong in that provider's adapter, with display metadata in
src/workers/providers.ts. Live readings and transcript parsing go through the shared provider interface. Server consumers and UI use the neutral usage shape and shared mapping insrc/workers/usage.ts; neither interprets raw provider fields. Both usage surfaces renderweb/src/workers/usage.tsxwithout provider branches or token counting.
Changes
- A refactor changes form, never outcomes: every input path keeps its result, guard order, side effects and error. Run
pnpm run lintafter each structural edit. - Write library and Node calls from the installed version's types, not from memory, and avoid deprecated APIs. Node 22.13 is the floor.
- Comment only for a non-obvious reason or constraint that no name can carry; rename instead of explaining.
- A change to behavior, CLI output or setup updates its docs, CLI help and shipped skills in the same change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
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.

