Index of every page on this site: llms.txt
All skills
n8n-io avatar

/env-var-docs

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

Writes and reviews the JSDoc on `@Env(...)` config properties. The docs team extracts these comments from source into the public environment variable reference, so they are user documentation, not code comments. Use when adding or changing an `@Env` property, a config class, or reviewing a PR that touches one.

  • 1 file
  • 5.9 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/n8n-io/n8n/env-var-docs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈81 tokens for metadata: the name and description. ≈1.4k when used: this file.

Description uses 4.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈330 characters, or 4.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Environment variable docs

The JSDoc above every @Env('...') property is exported almost verbatim into the environment variables reference on docs.n8n.io. The generated table has four columns: variable name, description, data type, default. Your JSDoc is the description column. The reader is a self-hosting operator, not an n8n developer.

Follow the n8n docs style guide for these comments. It overrides the ASD-STE100 rule in AGENTS.md for this one case. The rules below are the parts of that guide that matter for a one-paragraph description.

Rules

  • Every @Env property has a JSDoc. No exceptions. A missing comment ships as an empty description cell.
  • Write for the operator. Say what the setting does, when to change it, and what happens when it's unset or wrong. Don't explain why the code is written the way it is.
  • No code references. No file names, class names, function names, constants, license keys, or other internals the reader can't open. Values the operator types into the variable are fine and often needed, for example a credential type ID like googleOAuth2Api or a mode like postgresdb. The test: would the operator paste this into a config file, or would they need the source to know what it means? Details for developers go in a regular // comment on the implementation, not in the JSDoc.
  • No attack scenarios. Say what the setting protects, not how an attacker would exploit it. This is a public page.
  • Don't repeat the default. The default renders in its own column. Don't write "Defaults to true" or "Default: 1 hour". Do say what the unset state means when it's not obvious, for example "When unset, n8n uses the Redis host".
  • State units and formats. Say "in milliseconds", "in bytes", "a comma-separated list", "a JSON object". The data type column only says Number or String.
  • Use allowed values when the set is small. "One of sqlite, postgresdb." For a list, show one inline example in the sentence.
  • No JSDoc tags. No @example, @default, @see, @deprecated. The exporter copies the tag name into the docs. Put the example or the deprecation notice in a sentence instead.
  • Product names: "Gateway credits", not "n8n Connect" or "AI Gateway". "Publish a workflow", not "activate". n8n is always lowercase.
  • Style: present tense, active voice, second person. Use contractions. No em dashes, use a comma or a new sentence. No "e.g." or "i.e.", write "for example" and "that is". Spell out zero to nine, numerals from 10. Values the operator types stay numerals, for example "Set to 0". Sentence case. One idea per sentence. End every sentence with a period.
  • Plain words: "use" not "utilize", "lets you" not "allows you to", cut "powerful", "seamless", "simply", "it's important to note".
  • Length: one to three sentences. If the setting needs more, the extra belongs in a docs page the comment can't link to yet; keep the comment to what fits a table cell.

Examples

Bad, as found in the generated docs:

/**
 * Instance-level enablement for n8n Connect (AI Gateway). Licensed instances
 * are enabled by default; false opts out. Budget / free allowance still comes
 * from the license (`quota:aiGatewayBudget`).
 */

Wrong product name, a restated default, and an internal license key. Good:

/**
 * Whether Gateway credits are available on this instance. Set to false to
 * turn them off on a licensed instance. The credit allowance comes from your
 * license.
 */

Bad:

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to disable
 * expiry. Default: 1 hour.
 */

The default is already in the table. Good:

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to keep
 * entries until Redis evicts them.
 */

Bad:

/**
 * Comma-separated list of credential types for which overwrites are skipped
 * when the credential has been customized.
 * @example `N8N_SKIP_CREDENTIAL_OVERWRITE=zohoOAuth2Api,salesforceOAuth2Api`
 */

The @example tag lands in the description as literal text. Good:

/**
 * Comma-separated list of credential types to skip when applying credential
 * overwrites, for example `zohoOAuth2Api,salesforceOAuth2Api`. n8n skips an
 * overwrite only when a user has already changed one of its fields.
 */

Bad:

/**
 * Bind OAuth credential callbacks to the browser that initiated the flow.
 * When enabled, a session-scoped `n8n-oauth-binding` cookie is set on flow
 * initiation and verified on callback. Defeats phishing attacks where an
 * attacker injects an OAuth authorize URL into a victim's browser to land
 * tokens on the attacker's credential.
 */

Attack narrative and an internal cookie name on a public page. Good:

/**
 * Whether an OAuth credential connection must finish in the same browser
 * that started it. When enabled, n8n rejects the callback if it arrives
 * from a different browser.
 */

Review checklist

When you review a PR that adds or changes an @Env property, check each comment against this list and quote the fix in the review:

  1. JSDoc present.
  2. No code identifiers, file names, or internal keys.
  3. No default restated.
  4. Units, format, or allowed values stated.
  5. No JSDoc tags.
  6. No em dashes, Latin abbreviations, or filler words.
  7. Reads correctly as a sentence in a table cell with no surrounding context.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month

README badge

README badge for n8n-io/n8n/env-var-docs