agentleFS
leonardourcileonardourci/pnyx/.agents/skills/follow-conventions/SKILL.md

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.

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
  1. Very specific:

    Put guard clauses first: check invalid cases at the top, return or throw, and let the main flow read after them without extra indentation.

    line 20
  2. Very specific:

    Write conditions in their positive form.

    line 22
  3. Distinctive:

    Delete dead branches: an arm an earlier guard handled, a check on an already narrowed value, a fallback no caller can reach.

    line 23
  4. Very specific:

    Import a file in the same folder as ./file.ts.

    line 27
  5. Very specific:

    Write the file's real extension in the import: .ts under src/, .ts or .tsx under web/src/.

    line 28
  6. Distinctive:

    Write a rule the code checks in more than one place once, as a named helper every site imports.

    line 38
  7. Distinctive:

    Never drop an error to make code tidy.

    line 40
  8. Distinctive:

    Write library and Node calls from the installed version's types, not from memory, and avoid deprecated APIs.

    line 49

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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, return or throw, 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 = !known flag 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 the package.json aliases, even inside the same feature: #tasks/model.ts for src/tasks/model.ts and #web-shared/ui/icon.tsx for web/src/shared/ui/icon.tsx. ESLint rejects ../.
  • Write the file's real extension in the import: .ts under src/, .ts or .tsx under web/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 0 index 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 HydraError with its code at the failure site; guard() turns it into the CLI's structured error. A catch that 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 in src/workers/usage.ts; neither interprets raw provider fields. Both usage surfaces render web/src/workers/usage.tsx without 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 lint after 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.