Complete AGENTS.md Inventory and Claude Skills Migration Strategy

Purpose

Comprehensive analysis of all 25 AGENTS.md files and strategic plan for Claude Skills migration.

All AGENTS.md Files (Organized by Type)

🔀 ROUTING FILES (Not Specialized Knowledge)

Total routers: 4 files

---

🎓 SPECIALIZED KNOWLEDGE DOMAINS (Need Skills)

1. System Configuration

Skills needed: 4

2. NNT Ecosystem (PhD Research)

Skills needed: 3

3. Educational Games

Skills needed: 3

4. Vault Specialized Domains

Skills needed: 5 (excluding duplicate)

5. Technical Infrastructure

Skills needed: 5

---

Summary: AGENTS.md Breakdown

Total AGENTS.md files: 25
Unique Claude Skills needed: 20

---

The Problem with "One Skill to Rule Them All"

I was wrong earlier. You CAN'T have one vault-navigator skill because:

1. NNT compiler knowledge is COMPLETELY different from SWC Canvas LMS knowledge
2. Nix configuration patterns are unrelated to Godot game development
3. Each domain has specialized:
   • Technical stack
   • Commands/workflows
   • File structures
   • Problem-solving patterns

Example: If user asks "How do I configure zsh aliases?"

• Bad (one skill): Skill searches Convex for "zsh", loads article, doesn't know HOW to help with actual config edits
• Good (shell-config skill): Skill KNOWS:
  • Files live in ~/.config/zsh/conf.d/
  • Use chezmoi edit to modify
  • Apply with chezmoi apply && zshreload
  • Common patterns (PATH, aliases, functions)

---

Recommended Architecture: Hybrid (Routing + Specialized Skills)

Layer 1: One Routing Skill (Replaces ARF Routing Table)

markdown
<!-- ~/.claude/skills/context-router/SKILL.md -->
---
name: context-router
description: Route user questions to the correct specialized skill
when_to_use: Initial user question, before specialized skills are loaded
---

# Context Router Skill

## How It Works

1. Analyze user's question keywords
2. Query Convex metadata (if needed) OR check keywords directly
3. Recommend which specialized skill to load
4. Load that skill

## Routing Logic

User mentions "zsh", "shell", "aliases" → Load `shell-config` skill
User mentions "nnt", "compiler", "parsing" → Load `nnt-compiler` skill
User mentions "canvas", "gradebook", "swc" → Load `swc-teaching` skill
User mentions "godot", "jagquest", "game" → Load `jagquest-game` skill

## Fallback

If question is about vault articles (not specialized workflows):
- Query Convex articles table by keywords
- Read article via Obsidian MCP
- Answer from article content

Purpose: Lightweight router (replaces ~/AGENTS.md routing table)

Layer 2: 20 Specialized Skills (One Per Domain)

Each skill contains:

• Workflows - How to accomplish tasks in that domain
• File locations - Where files live
• Commands - Specific CLI commands/shortcuts
• Patterns - Domain-specific best practices
• References - Can still query Convex/vault for additional knowledge

Example: shell-config skill:

markdown
<!-- ~/.claude/skills/shell-config/SKILL.md -->
---
name: shell-config
description: Zsh configuration, aliases, PATH, environment variables via chezmoi
when_to_use: User asks about shell configuration, zsh, aliases, PATH, environment
---

# Shell Configuration Skill

## File Locations

**Config directory:** `~/.config/zsh/conf.d/`

| File | Purpose |
|------|---------|
| `00-environment.zsh` | PATH, EDITOR, fzf, asdf init |
| `10-aliases.zsh` | Command shortcuts, functions |
| `20-display.zsh` | Monitor config (displayplacer) |
| `99-local.zsh` | Machine-specific (optional) |

## Workflows

### Adding a New Alias

1. Edit via chezmoi:
   ```bash
   chezmoi edit ~/.config/zsh/conf.d/10-aliases.zsh

2. Add alias:

   zsh
   alias gs='git status'
   

3. Apply and reload:

   bash
   chezmoi apply && zshreload
   

Modifying PATH

1. Edit environment file:

   bash
   chezmoi edit ~/.config/zsh/conf.d/00-environment.zsh
   

2. Add to PATH:

   zsh
   export PATH="/new/path:$PATH"
   

3. Apply:

   bash
   chezmoi apply && exec zsh
   

Common Patterns

Function with arguments:

zsh
function mkcd() {
  mkdir -p "$1" && cd "$1"
}

Conditional PATH addition:

zsh
<span class="wikilink-broken" title="Page not found:  -d /opt/homebrew/bin "> -d /opt/homebrew/bin </span> && export PATH="/opt/homebrew/bin:$PATH"

Troubleshooting

Alias not working

• Check for typos in alias definition
• Run zshreload or exec zsh
• Verify file is sourced: grep "conf.d" ~/.zshrc

PATH not updated

• Check load order (00-environment.zsh loads first)
• Verify chezmoi applied: chezmoi diff
• Check for conflicts with .zshenv or .zprofile

Related Knowledge

For additional context, query Convex articles:

• keywords: ["zsh", "shell", "configuration"]
• domain: "Computer Tech/Unix"

**This skill knows HOW to configure zsh, not just WHERE to find docs.**

---

## Migration Strategy: Phased Approach

### Phase 1: High-Value Skills (Top 5)

Convert the most frequently used AGENTS.md to skills:

1. **shell-config** - Daily use, highly specific workflows
2. **nnt-compiler** - Active PhD research, complex
3. **registry-database** - Your current work focus
4. **swc-teaching** - Semester tasks, Canvas API
5. **obsidian-workflows** - Vault management

**Timeline:** This weekend (5 skills)

### Phase 2: Medium Priority (Next 10)

6. terminal-config
7. editor-config
8. dev-tools-config
9. nnt-docs
10. audio-discovery
11. web-projects
12. nix-system
13. zellij-mcp
14. outlook-mcp
15. phd-dissertation

**Timeline:** Next 2 weeks

### Phase 3: Low Priority (Remaining 5)

16. acdm-game
17. jagquest-game
18. plant-game
19. family-finance
20. daily-notes

**Timeline:** As needed

### Phase 4: Deprecate AGENTS.md Files

**After all skills created:**
- Keep router files as documentation (~/AGENTS.md, ~/.config/AGENTS.md)
- Delete specialized AGENTS.md files (clutter vault)
- Metadata moves to Convex + article frontmatter

---

## Convex Integration (Revised)

**Articles table needs:**
- `keywords` - For discovery
- `domain` - For categorization
- `frontmatter` - Raw YAML storage

**BUT:** Specialized skills DON'T query Convex for workflow knowledge.

**Convex is for:**
- ✅ Finding relevant ARTICLES (educational content)
- ✅ Listing available articles in a domain
- ❌ Storing workflow instructions (that's in skills)

**Example split:**

| Knowledge Type | Storage | Example |
|----------------|---------|---------|
| **Educational article** | Vault + Convex | "How Zsh Aliases Work" (conceptual) |
| **Workflow** | Claude Skill | "How to add alias via chezmoi" (procedural) |
| **File locations** | Claude Skill | "Aliases in ~/.config/zsh/conf.d/10-aliases.zsh" |
| **Commands** | Claude Skill | "chezmoi edit + apply + zshreload" |

---

## Token Efficiency Comparison

### Old (ARF Only)

User asks: "How do I add a zsh alias?"

1. Agent reads ~/AGENTS.md (2000 tokens)
2. Finds route to ~/.config/AGENTS.md (500 tokens)
3. Finds route to ~/.config/shell/AGENTS.md (800 tokens)
4. Reads shell AGENTS.md (1500 tokens)
5. Still doesn't have specific workflow, might query vault

**Total:** ~5000 tokens to get basic routing

### New (Skills + Convex)

User asks: "How do I add a zsh alias?"

1. Context-router skill loaded at startup (50 tokens frontmatter)
2. Recognizes "zsh", "alias" keywords
3. Loads shell-config skill (100 tokens frontmatter)
4. Shell-config skill auto-invoked (2000 tokens full skill)
5. Has complete workflow, answers immediately

**Total:** ~2150 tokens + immediate answer

**Savings:** 60% token reduction + faster response

---

## Next Steps (Concrete)

### 1. Create Context-Router Skill (15 min)

```bash
mkdir -p ~/.claude/skills/context-router
cat > ~/.claude/skills/context-router/SKILL.md << 'EOF'
[routing logic based on keywords → skill mapping]
EOF

2. Create Shell-Config Skill (30 min)

bash
mkdir -p ~/.claude/skills/shell-config
cat > ~/.claude/skills/shell-config/SKILL.md << 'EOF'
[complete shell config workflows]
EOF

3. Test Skills

bash
# In Claude Code
# Ask: "How do I add a zsh alias?"
# Observe: Does context-router load shell-config?
# Verify: Does it provide complete workflow?

4. Add Keywords to Articles Table

typescript
// convex/schema.ts - Update articles table
keywords: v.array(v.string()),
domain: v.string(),
frontmatter: v.any(),

5. Create Vault Sync Script

bash
# scripts/sync-vault-to-convex.ts
# Scan .md files → Extract frontmatter → Upsert to Convex

---

Final Architecture

User Question
    ↓
Claude Code (loads all skill frontmatter - ~1000 tokens total)
    ↓
context-router skill (decides which specialized skill)
    ↓
Specialized skill (20 options)
    ├── Has workflows/commands (answers directly)
    └── Can query Convex (if needs article reference)
            ↓
        Convex articles table (keyword search)
            ↓
        Obsidian vault (read article content)

Benefits:

• ✅ Token efficient (progressive disclosure)
• ✅ Fast (auto-invocation)
• ✅ Specialized (20 domain experts)
• ✅ Scalable (Convex for article discovery)
• ✅ Clean vault (no AGENTS.md clutter)

---

Answer to Your Questions

"Do all AGENTS.md need to become skills?"

YES - but only 20 specialized ones (not 4 routers).

"Is this better?"

YES - but for different reasons than I said earlier:

• Not "one skill" - 20 specialized skills
• Not just database - skills have procedural knowledge
• Not replacing ARF - evolving it into modern architecture

"Will vault be cleaner?"

YES:

• Delete 20 specialized AGENTS.md files (clutter)
• Keep 4 router files as documentation
• Skills live in ~/.claude/skills/ (out of vault)

Should I start creating the first 2 skills (context-router + shell-config)?