Nf Ignore

nf-ignore

Audit and update .gitignore for AI coding tools and env files. Only ignores personal/local files — team-shared configs (rules, instructions, shared settings, framework env defaults) stay committed.

Intent — apply the standard, judge deviations, override; never re-ask the defaults

The asset files ARE the canonical standard. The job is to bring the project's .gitignore up to that standard, not to ask the user to assemble it. So:

• Apply wholesale via scripts/apply.sh. The full canonical block (all 5 personal prefixes, all tool patterns, the env block for the detected type) is applied as one unit. NEVER present an AskUserQuestion / menu asking which canonical patterns or personal prefixes to include — that is not a user decision, and improvising such a picker is what produces the wrong "pick your OOTB defaults" prompt (and Invalid tool parameters when overstuffed).
• Re-trigger = judge + override, not suggest-from-scratch. On an already-set-up project, compare the current .gitignore against the canonical standard: top up missing/new patterns (the script does this), and JUDGE deviations — overly-broad patterns to replace, tracked files now caught by the rules. Surface those as override decisions, not as a re-pick of the defaults.
• The additive top-up is NEVER confirmed — re-triggering /nf-ignore IS the consent to upgrade. Both Case 1 (the ambiguous fast path) and Case 2 (a re-trigger on a real stack) apply the additive block — ai-tools + the type's env block, dedup'd — immediately, then report. The ONLY thing put to the user is an AskUserQuestion for concrete OVERRIDE decisions that edit/remove existing lines: replace an overly-broad pattern, git rm --cached a now-ignored tracked file. No such decisions → no question at all. Nothing about WHICH defaults to add is ever asked.
• Two things the script now does deterministically — NEVER ask about either: (1) it skips pattern lines already present in the target, so applying a block onto a project that already has .DS_Store / node_modules/ / .env produces NO duplicate lines (no "should I dedup the block?" question); (2) it rewrites a blanket tool-dir ignore that shadows a canonical whitelist — e.g. a pre-existing .codex/ becomes .codex/* so the asset's !.codex/rules/ survives (consolidate-not-clobber, the established convention). Both are reported in the JSON (normalized), never put to the user as a choice.

Workflow

Step 1 — Detect project type

Run scripts/detect.sh from the repo root. It outputs JSON:

{
  "type": "framework" | "plain" | "mixed" | "ambiguous",
  "framework": "vite|next|nuxt|astro|sveltekit|remix|null",
  "workspaces": [{ "path": "...", "type": "framework|plain", "framework": "..." }]
}

Case 1 — fast path — type == "ambiguous" (fresh start: blank project / no detected stack):

Do NOT block on asking which convention applies. Immediately write a quick baseline so Claude Code personal files and common junk are ignored from the start:

1. Run scripts/apply.sh (no args → repo root). For an ambiguous project it deterministically reconciles the ai-tools block AND the common-baseline block: appends the full block when absent, or TOPS UP only the pattern lines missing from the current asset when the block already exists (so an updated asset propagates on re-trigger), preserving existing formatting. NEVER hand-write or paraphrase the asset contents — always run the script so output is identical standalone vs. inline under a wrapper skill.
2. Report in one short block: what was written + the note that env policy is the conservative baseline (.env blocked, .env.example kept).
3. Add: "Re-run /nf-ignore once a stack is set up (package.json / framework config) for stack-specific env rules."

This fast path skips Steps 2–4 (no audit, no override card — a blank project has nothing to override) because the write is purely additive to a project with no real .gitignore policy yet. Stop after the post-apply reminder (Step 5).

Step 2 — Audit existing .gitignore

Read the project's .gitignore (if it exists). Check for:

• Overly broad patterns blocking team-shared files — see references/tool-shared-files.md. NOTE: a blanket tool-dir ignore that shadows a canonical whitelist (e.g. .codex/ vs the asset's !.codex/rules/) is fixed automatically by apply.sh — do not flag it as a deviation to ask about.
• Env policy mismatch:
• Framework project with .env.* pattern → blocks shared defaults; replace with .env*.local.
• Plain Node.js with only .env*.local → secrets in .env are leaking; add strict block.
• Mixed monorepo with one-size-fits-all pattern → suggest scoped rules per workspace.
• Unknown or suspicious patterns that look AI- or env-related but aren't recognised — surface to user, do not skip.

Step 3 — Case 2: apply the additive top-up, then report a headline

This is the re-trigger / first-real-stack path (Case 2) — the project has a real .gitignore and a detected stack. The additive top-up is applied WITHOUT a confirm: the re-trigger itself is the consent to upgrade patterns.

1. Run scripts/apply.sh (no args → repo root). It reconciles the ai-tools block plus the env block for framework/plain: appends a full block when absent, or tops up only the missing pattern lines when the block already exists — so re-triggering an old project picks up patterns added to the asset since. Format-preserving and additive-only (never removes a line). NEVER hand-write or paraphrase asset contents — always run the script so inline execution under a wrapper skill matches a standalone run.
2. mixed monorepo (needsMixedEnv: true): the script reconciles ai-tools only — then additively expand assets/env-mixed.gitignore.tmpl, one {{WORKSPACE_PATH}} block per detected plain workspace. Still additive, still no confirm.
3. Read the JSON (added / toppedUp / upToDate / normalized / trackedIgnored / needsMixedEnv) and print a 2-3 line headline of what was DONE — not the old four-section wall:

• Detected: type + framework / workspace breakdown.
• Net effect: +N dòng added | env | normalized: | 0 removed.
• If trackedIgnored is non-empty: note K tracked file(s) now ignored — decision below.

Step 4 — Override decisions (AskUserQuestion — only if there are any)

The additive top-up already landed in Step 3. What remains are the decisions that EDIT or REMOVE existing lines — genuinely the user's call. Collect two lists:

• Overly-broad patterns to replace found in Step 2 (e.g. a framework project with .env.* → replace with .env*.local).
• trackedIgnored from the apply JSON → each needs git rm --cached (git rm -r --cached for a directory) to take effect.

If BOTH lists are empty → no question; you are done (go to Step 5).

Otherwise present ONE AskUserQuestion:

• ≥2 decisions → multiSelect: true, one option per decision. Each option's preview shows the exact line change (.env.* → .env*.local) or the git rm command. Ticked = apply; un-ticked = leave as-is.
• exactly 1 decision → single-select with two options (Áp dụng / Bỏ qua), since the tool requires ≥2 options.

Execute ONLY the selected decisions: rewrite/replace the pattern lines in .gitignore, and run the confirmed git rm --cached commands. NEVER run git rm on an un-ticked file.

This AskUserQuestion is the ONE place /nf-ignore questions the user. It never asks which canonical defaults to add — those were auto-applied in Step 3.

Step 5 — Post-apply reminder

• Suggest git status to verify no newly untracked team-shared files appeared.
• The git rm --cached decisions are handled in Step 4 (only the ticked ones run); note those files stay on disk — only their git tracking is dropped.
• If not in a git repo, warn but note the .gitignore was still written.

Rules

• NEVER present a picker / AskUserQuestion / menu asking WHICH canonical patterns or personal prefixes to add. The asset is the standard; scripts/apply.sh applies it wholesale and additively. The ONE user-facing AskUserQuestion is Step 4's override decisions (replace an overly-broad pattern, git rm --cached a now-ignored tracked file) — and only when such decisions exist.
• Two cases: Case 1 — ambiguous/blank → common-baseline + ai-tools via the Step 1 fast path, no questions. Case 2 — real stack (plain/framework/mixed) → ai-tools + env block auto-applied (Step 3), then the Step 4 override card only if there are overrides.
• The additive top-up is applied WITHOUT a confirm gate — re-triggering /nf-ignore is itself the consent to upgrade patterns. The additive write happens BEFORE the report (write-then-report) in every case, because additive-only changes never remove a line.
• A re-trigger JUDGES the current .gitignore against the canonical asset and reconciles/overrides toward it — it does NOT re-offer the out-of-the-box defaults as a choice.
• Confirmation is required ONLY for override decisions that edit/remove lines or untrack files (Step 4) — never for the additive top-up.
• NEVER remove existing patterns without asking.
• NEVER silently skip problems — always surface them.
• Preserve existing .gitignore formatting.
• Skill scope is .gitignore only — do not create or modify .env.example or other files.

Resources

• scripts/detect.sh — runs framework + workspace detection; outputs JSON
• scripts/apply.sh — deterministic reconcile of ai-tools + the type-appropriate env/baseline block (idempotent, format-preserving, dedups patterns already present, and rewrites blanket tool-dirs that shadow a whitelist → normalized). The apply step MUST go through this, never a hand-written paraphrase.
• assets/ai-tools.gitignore — AI tool personal-file patterns (always applied)
• assets/common-baseline.gitignore — language-agnostic baseline (OS/editor/logs/deps/env); used by the ambiguous fast path
• assets/env-framework.gitignore — env block for Vite/Next/Nuxt/Astro/SvelteKit/Remix projects
• assets/env-plain.gitignore — env block for plain Node.js projects
• assets/env-mixed.gitignore.tmpl — env template for mixed monorepos; {{WORKSPACE_PATH}} expanded per plain workspace
• references/tool-shared-files.md — table of shared files that must be committed, plus overly broad pattern reference

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: llawliet11
• Source: llawliet11/claude-skills-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.