# Audit Links

> Validate vault graph consistency and structural integrity

- Skill: `majiayu000/audit-links` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/audit-links`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/audit-links/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/audit-links

---


## 🔍 Audit Links Skill

Fast audit of vault structure to catch:
- Orphan papers (not linked to any project)
- Orphan projects (not linked to any MOC)
- Broken bidirectional links (paper→project without reciprocal project→paper)
- Forbidden concept links (e.g., `[[Attention Mechanism]]`)
- Papers linking directly to MOCs (forbidden)
- Malformed wiki links

---

## CRITICAL RULES

**Vault constraints (non-negotiable):**
1. Every paper in `Reading/` must link to ≥1 project in `Projects/`
2. Every project in `Projects/` must link to ≥1 MOC in `MOCs/`
3. Bidirectional links: If paper→project exists, project→paper must exist
4. Papers **never** link directly to MOCs
5. Papers link **only** to projects and other papers
6. Concept/method/technique links forbidden (e.g., `[[Transformer]]`, `[[Attention Mechanism]]`)

---

## WORKFLOW

### 1. Get audit scope
Read `.claude/vault_maintanance.md` and note the `audit_links:` timestamp.

**Default: incremental scan** — only files modified after the `audit_links:` timestamp.
Use `find Reading/ Projects/ MOCs/ -newer <reference_file>` to scope the file set.
To use a reference file, write the timestamp as a temp file: `touch -t YYYYMMDDHHMI /tmp/audit_ref && find ... -newer /tmp/audit_ref`

Only run a full scan if:
- The user explicitly requests it ("full audit", "scan everything")
- No `audit_links:` timestamp exists yet

### 2. Run lightweight scan

**For papers in `Reading/`:**
- Extract all `[[wiki links]]` from each paper
- Verify each link points to a project in `Projects/` or paper in `Reading/`
- Flag: Papers with zero project links (orphan papers)
- Flag: Papers linking directly to `MOCs/` files (forbidden)
- Flag: Concept links like `[[Attention]]`, `[[Transformers]]` (forbidden)

**For projects in `Projects/`:**
- Extract all `[[wiki links]]` from each project
- Verify each links to MOC or paper
- Flag: Projects with zero MOC links (orphan projects)

**For bidirectional consistency:**
- For each paper→project link found: verify reciprocal project→paper link exists
- Flag: Missing reciprocal links

### 3. Compile report
Group findings by violation type:
1. **Orphan papers** (not linked to any project)
2. **Orphan projects** (not linked to any MOC)
3. **Broken bidirectional links** (paper→project without project→paper)
4. **Forbidden concept links** (in papers)
5. **Forbidden paper→MOC links**
6. **Malformed links** (broken wiki syntax)

Include:
- File name
- Problematic link/content
- Suggested fix

### 4. Present findings
- Show violations by category
- Prioritize by severity (orphans > broken bidirectional > concept links)
- Offer fixes: "Should I remove this link?" / "Should I add reciprocal link?"

### 5. Apply fixes
Only with user approval:
- Remove orphan papers/projects (ask first)
- Fix broken bidirectional links
- Remove forbidden concept links
- Remove paper→MOC links

### 6. Update vault_maintanance.md
After completing the audit (regardless of whether fixes were applied):
- Run `date` via Bash to get the current system time
- Read `.claude/vault_maintanance.md`
- Update `audit_links:` line to current date and time in format `DD-MM-YYYY HH:MM`
- Reset `papers_since_audit_links:` to `0`
- Reset `projects_since_audit_links:` to `0`
- Write the updated file

**Example update:**
```
audit_links: 10-02-2026 14:35
```

---

## TOKEN EFFICIENCY

**Optimizations:**
- Use grep patterns to find links fast: `\[\[.*\]\]`
- Don't read full file contents unless necessary
- Process files by type (papers, projects, MOCs)
- Early exit on first issue per file
- Report summaries, not line-by-line details

**Avoid:**
- Reading every file in full (extract links only)
- Deep analysis of content (only validate structure)
- Redundant checks across multiple passes

---

## OUTPUT RULES

- Concise summary first
- Group violations by type
- Each violation: file name + issue + suggested fix
- No prose, bullets only
- Fast scan report (~100-200 tokens)

---

## SELF-CHECK

✅ Did I scan all papers for orphans?
✅ Did I check all projects for MOC links?
✅ Did I verify bidirectional consistency?
✅ Did I identify concept links in papers?
✅ Did I find paper→MOC direct links?
✅ Report grouped by violation type?
✅ Did I get user approval before fixing?
✅ Did I update vault_maintanance.md with current timestamp and reset counters?