nijaru/ai-context
dot_claude/skills/ai-context/SKILL.md
Full conventions for the ai/ persistent context system — file roles, index discipline, frontmatter spec, consolidation rules, and DECISIONS.md compaction. Use when operating on ai/ files or enforcing conventions mid-session.
testing
Updated Apr 22, 2026
$ install --global
skillsauthnpx skillsauth add nijaru/dotfiles ai-contextInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 4:46 PM22.7s1 file scanned
SKILL.md
- name:
- ai-context
- description:
- Full conventions for the ai/ persistent context system — file roles, index discipline, frontmatter spec, consolidation rules, and DECISIONS.md compaction. Use when operating on ai/ files or enforcing conventions mid-session.
- allowed-tools:
- Read, Write, Edit, Glob, Grep, Bash
ai/ Context Conventions
Reference for operating within an established ai/ directory. For initialization or audit/migration, use the setup-ai skill instead.
Structure
ai/
├── README.md # Index: pointers only, ~150 chars/entry, no content
├── STATUS.md # Phase, focus, blockers — updated every session
├── DESIGN.md # Current architecture — answers "what is it?"
├── DECISIONS.md # Why decisions were made — Principles + Log sections
├── PLAN.md # Active plan or sprint index (managed by /sprint)
├── research/ # Investigation docs
├── design/ # Detailed design docs
├── review/ # Review outputs
├── sprints/ # Sprint detail files (NN-name.md) — created by /sprint
└── tmp/ # Scratch (gitignored)
File Roles
| File | Purpose | Update Rule |
| :------------- | :---------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| README.md | Index only — pointers, ~150 chars/entry, no content | Immediately when any topic file is added/changed/deleted |
| STATUS.md | Phase, active focus, blockers | Every session; on focus shifts and blockers |
| DESIGN.md | Current architecture — answers "what is it?" | When architecture changes |
| DECISIONS.md | Why it is that way. Principles (distilled) + Log (recent ~20 entries) | Append to Log; compact when Log > ~20 entries |
| PLAN.md | Active plan. Flat doc or sprint index with ai/sprints/NN-name.md files | Update as sprints progress; extract outcomes to DECISIONS/DESIGN then replace |
Index Discipline
README.md is pointers only — format: - [Title](path) — one-line hook
- Write to any file → update
README.mdimmediately. Index must stay synchronized. - Verify links are live. Remove dead links.
- Don't persist derivable facts — if it's grep-able from code or git history, don't write it to
ai/. ai/is hints, not truth — verify against code when it matters.
Topic File Frontmatter
All files in research/, design/, review/ must start with:
---
date: YYYY-MM-DD
summary: one-line description
status: active | resolved | stale
---
Topic files in subdirs only get README.md entries if actively referenced by current work.
DECISIONS.md Compaction
When Log section exceeds ~20 entries:
- Read oldest Log entries
- Identify recurring themes → distill into concise Principles at the top
- Remove distilled entries from the Log
- Keep recent ~10 entries verbatim
Run /setup-ai to do this automatically.
Consolidation Rules
- Merge before multiplying — one focused file beats three overlapping ones.
- Delete resolved files — don't mark done, delete.
status: resolved= candidate for deletion. - Stale threshold — topic files unmodified for 3+ months with no
README.mdreference → verify relevance, delete if stale. - No derivable facts — grep-able code facts don't belong in
ai/.
Workflow
research/ → DESIGN.md → /sprint → PLAN.md → code → review/
Format: Tables/lists over prose. Answer first, evidence second.
Project Config
AGENTS.md is primary in own repos. Symlink at repo root: ln -s AGENTS.md CLAUDE.md. OSS/external repos often use ./CLAUDE.md — follow whatever convention is present.
Keeping ai/ and .tasks/ local (not committed):
echo 'ai/' >> .git/info/exclude
echo '.tasks/' >> .git/info/exclude
→ git-local-exclude skill for details.
Related Skills
nijaru/second-pass
development
VerifiedTrustedCommunity
Use after completing a bug fix, feature, refactor, or tk task when the first implementation taught enough context to replace it with a simpler, cleaner, or more coherent version before finalizing.
SKILL.mdUpdated Apr 25, 2026
nijaru/zig-expert
development
VerifiedTrustedCommunity
Use when writing, migrating, or reviewing Zig code across recent stable versions (0.14-0.16), especially to correct stale syntax or stdlib, build.zig, allocator, formatting, or runtime API knowledge.
SKILL.mdUpdated Apr 22, 2026
nijaru/writer
documentation
VerifiedTrustedCommunity
Use when reviewing or revising text (prose, docs, commits) to remove AI patterns and improve voice/clarity.
SKILL.mdUpdated Apr 22, 2026
nijaru/twitter
content-media
VerifiedTrustedCommunity
Use when fetching X/Twitter post content by URL, or searching for recent X posts.
SKILL.mdUpdated Apr 22, 2026