| name | update-instructions |
| description | Audit and update all agent instruction files, skills, and AGENTS.md for this Next.js 16 + Mantine 9 personal blog. Explores the live codebase to find outdated rules, missing sections, and stale references, then applies fixes. Use when the codebase has changed significantly, after adding a major feature, or when instructions feel out of sync with reality.
|
Update Instructions
When to Load This Skill
- User says "update the instructions", "update the docs", "keep instructions in sync"
- User says "the instructions are outdated"
- After implementing a major feature (e.g., caching, new lib module, new component pattern)
- After a dependency upgrade that changes patterns (Next.js major, Mantine major)
Files to Audit
| File | Purpose |
|---|
AGENTS.md | Top-level project overview, architecture map, key rules |
.agents/instructions/code-standards.instructions.md | Coding conventions, patterns, rules |
.agents/instructions/writing-style.instructions.md | Prose style rules |
.agents/skills/*/SKILL.md | Domain-specific workflow skills |
Process
Step 1: Explore the Live Codebase
Spawn a sub-agent (or run searches in parallel) to collect ground truth:
- Project metadata — read
package.json for exact dependency versions and npm scripts
- Config — read
next.config.ts for enabled features (cacheComponents, reactCompiler, image config, etc.)
- lib/ inventory — list every file; note what each exports and whether it is server-only
- components/ inventory — list every directory; note
'use client' usage, CSS modules, test coverage
- app/ routes — list all pages and API routes
- Key patterns in use — scan for
'use cache', Suspense, dangerouslySetInnerHTML, logging calls
- Test setup — read
vitest.config.ts for globals, environment, coverage settings
- Deployment — read
nixpacks.toml and next.config.ts for deployment-relevant settings
Step 2: Compare Against Each File
For each file in the audit list, check for:
- Stale facts: version numbers, file names, directory paths that no longer match the codebase
- Missing sections: patterns that exist in the codebase but are not documented
- Wrong rules: rules that contradict current practice (e.g., "do not use X" when X is now used)
- Redundancy: content duplicated across files — keep the canonical location, trim the copy
- Out-of-scope content: detail that belongs in a different file (e.g., architecture in code-standards instead of AGENTS.md)
Step 3: Plan Changes
Before editing, present a concise diff plan:
AGENTS.md
- Update architecture block (add proxy.ts, lib/axiom/, photos.ts)
- Update Key Rules (dangerouslySetInnerHTML, axiom/server.ts import rule)
code-standards.instructions.md
- Remove Project Structure section (redundant with AGENTS.md)
- Update Routing rule (API routes exist for infra concerns)
- Add Logging section (Axiom server/client patterns)
- Add Cache Components section
skills/next-cache-components/SKILL.md
- No changes needed
Ask the user to confirm before writing any changes.
Step 4: Apply Changes
Use multi_replace_string_in_file for multiple edits to the same file in one call.
Rules for edits:
- Drop sections only when the content is fully covered elsewhere or is factually wrong
- Add sections when a real pattern exists in the codebase but has no documentation
- Keep each file focused on its purpose (AGENTS.md = overview; code-standards = rules; skills = workflows)
- Do not add prose explanations — use bullet points and short imperative statements
- Do not create new files unless a genuinely new topic has no home
Step 5: Validate
After all edits:
- Re-read each modified file end-to-end and check for internal consistency
- Confirm no rule in one file contradicts a rule in another
- Report a brief summary of every change made
Scope Boundaries
This skill updates documentation only — it does not change source code, tests, or configuration files. If exploration reveals a code issue worth fixing, note it in the summary for the user to address separately.
