Claude Expert

Training data already has baseline Claude Code / SDK / API knowledge. The marginal value of another docs fetch is low. The marginal value of a fresh changelog, GitHub diff, or community post is high — that's where new patterns, regressions, and clever hacks live.

Prioritize, in order:

1. SDK + CLI changelogs — diff since last refresh.
2. Anthropic engineering + news posts — announcements call out capabilities docs haven't caught up with.
3. Active GitHub repos — commits in the last 90 days on the watched-repos list in references/11-ecosystem.md.
4. Community — the signal you can't get elsewhere: what breaks in practice.
5. Official docs — only for grounding a specific claim. Don't re-read the whole tree.

When answering, surface fresh finds first — "this shipped in SDK 0.4.0 last week" beats "the docs say X."

Workflow for every invocation

1. Check library freshness. Grep references/INDEX.md for the freshness: block. Thresholds:
   • Official track (01–09): 30 days.
   • Community track (10–11): 14 days — shifts faster.
   • Missing library → step 2a. Relevant topic stale → step 2b. Otherwise → step 3.

2a. Full bootstrap (empty library). Read references/bootstrap-prompt.md and dispatch /internet-researcher with it. Write INDEX.md when done. Then step 3.

2b. Targeted refresh. Dispatch /internet-researcher with a narrow prompt naming only the stale topic(s). For community topics (10, 11), attach the source list from references/refresh-sources.md — otherwise the researcher falls back to docs and produces empty community files. Bump last_refresh in INDEX.md. Then step 3.

3. Answer from the library. Grep the relevant topic file(s). If the user has a problem, scan 11-ecosystem.md for a 3rd-party solution before suggesting they build one. Cite the cache path or URL for anything non-trivial.

4. Verify before recommending action. If the user is about to install, run, or commit something, double-check the specific claim against the library — not training data. For community recommendations, verify the repo has commits in the last 90 days.

Growing the library

The topics in references/ are a baseline, not a ceiling. Extend it whenever you discover:

• A named plugin, skill, agent, or repo not cached → fetch README + plugin.json, capture under 11-ecosystem.md or a dedicated plugin-<name>.md.
• A "what's the best way to X?" with no library hit → search GitHub/Reddit/HN, capture the top 2–3 patterns.
• A changelog or release note revealing a feature the docs don't cover yet → snippet under the matching topic file.
• A pain-point with no entry in the solution table → add it.

When you grow the library, register the new file in INDEX.md (topic map + freshness block).

Decision table — skill vs agent vs hook vs command vs MCP vs plugin

Third-party solution finder

Before suggesting the user build anything non-trivial, grep references/11-ecosystem.md for an existing solution. If hit: "Instead of building, consider <repo> — it does X. Read: <file>. Caveats: <community-linked caveats>." If miss: say so explicitly, then propose building. Never silently skip the library check. If the pain-point isn't indexed, add it — next refresh picks up the new signal.

Memory rule (no append-only logs)

When the user says "remember X": integrate X in place into the relevant topic file. Do not append to a dated journal. Append-only logs grow unboundedly; every invocation eventually loads them and pollutes context.

Workflow:

1. Pick the right topic file (hook preferences → 04-hooks.md, skill-authoring → 02-skills.md, etc.).
2. Edit the file: drop the fact into the existing table/section, or add a short ## User preferences section. Tag with <!-- noted YYYY-MM-DD -->.
3. Truly cross-cutting fact → add under ## User preferences in INDEX.md, not a new file.

Do not touch auto-memory (~/.agents/memory/) — skill knowledge stays in the skill.

Self-maintenance

• When the library contradicts current behavior, correct it in place with <!-- corrected YYYY-MM-DD: <what> -->. Don't just answer and move on.
• If a topic is generating frequent corrections, backdate its last_refresh in INDEX.md so the next invocation triggers a refresh.
• Major Claude Code release lands → refresh the whole library, not one topic.
• Query, don't Read. grep for a specific fact; only Read the whole file when you need to edit.

Skill + hook authoring principles (apply when writing them)

Skill authoring is the user's most frequent ask. Encode these into every skill/hook you produce:

SKILL.md shape

For the generic "description-as-retrieval-index" and "progressive disclosure" principles, see /metaprompt. Claude-Code-specific notes:

• Description caps around 1024–1536 chars (Anthropic's catalog-slot limit). Lead with triggers; cut prose.
• Body has no length cap — it's lazy-loaded. The real test: what fraction of invocations reads this section? Rare-fire content (bootstrap prompts, one-time setup, long URL lists) → references/. Every-invocation content (workflow, memory rule, decision tables) → inline.
• One concern per reference file. A file that mixes template + style + index-format is three files.
• No duplicated surfaces. If a reference has a template and SKILL.md shows the same template, delete one. If a script has --help, don't re-list commands in SKILL.md.
• Preserve unknown frontmatter. When editing any SKILL.md / .agent.md / .instructions.md / CLAUDE.md, pass through any YAML key you don't own (applyTo, globs, other tools' keys) unchanged — order-preserving, comment-preserving, type-preserving. Complain only when a key this skill owns conflicts with external authority; never complain about foreign keys. Full rule: references/02-skills.md → Frontmatter-preservation rule.

Catalog / index files

• Agents query, humans browse, generators render. Never instruct an agent to Read an unbounded appended file. Expose script.sh find|list|has instead.
• Catalog = records; view = rendered. Records are structured (JSON or frontmatter). Views regenerate on demand. Hand-authored Markdown is for editorial content (narratives, templates, rules) — not logs.

Lessons / notes / journals

• No append-only logs in references/. They balloon; every invocation eventually loads them. Promote durable lessons to the relevant topic file; drop single-session quirks.
• If a lesson doesn't deserve an in-place edit, it doesn't deserve a file.

Hooks

• PreToolUse blocks; PostToolUse informs. Use PreToolUse for policy enforcement; agents rationalize past Post-hook warnings.
• "Whenever the user says/does X" = hook, not memory. The harness executes hooks; memory only gets read when a skill loads it.

Subagent dispatch (Claude Code specifics)

For generic parallel-vs-serial, model-tier, and worker-output rules, see /metaprompt. Claude-Code-specific:

• .agent.md tools: allowlist is the only enforcement — the agent cannot escape it. Read-only reviewers: Read, Grep, Glob. Action subagents: add Edit, Bash, or Task only as needed.
• model: inherit vs fixed. Fix the model only when the subagent's job class is stable (e.g., a Haiku-class scanner). Otherwise inherit so the parent's choice propagates.
• Isolation — each subagent gets its own context. Don't pass state by stuffing it into the prompt; use files the agent can read.

Cross-skill etiquette

• Don't pull cross-project facts into a skill's references — that's what auto-memory and project CLAUDE.md are for.
• When a new skill needs fresh community signal, point it at /internet-researcher. Don't bundle research inside the skill body.

The corpus-agnostic versions of these principles (catalog-vs-view, one-concern-per-file, frontmatter-as-relationship-graph, no-append-only-logs, activation-frequency splitting, mark-don't-delete) live in /librarian. The prompting-craft versions (model selection, caching, tool schemas, trigger density, parallel dispatch, extended thinking) live in /metaprompt. This skill is the Claude Code specialization — the mechanics of the artifacts themselves. Hand off to /librarian for plain Markdown organization or /metaprompt for prompting craft; don't re-derive those rules here under a different name.

See ~/.agents/skills/internet-researcher/SKILL.md for the reference design these principles came from.

Where artifacts live — and where to commit changes

The user's personal Claude artifacts are tracked in a git repo and surfaced into ~/.agents/ via symlinks. Know which location owns which file before you edit or commit.

Repos

Layout in ai-tools

src/skills/<name>/            ← canonical home for a personal skill
src/agents/<name>.agent.md    ← canonical home for a personal agent wrapper
src/scripts/                  ← shell scripts (bash + ps1 pairs)
src/profile.d/                ← shell profile snippets
scripts/link-skill.{sh,ps1}   ← the symlink manager
.agents/skills/link-skill/    ← project-scope skill documenting the workflow

How ~/.agents/ maps back

Fast triage: ls -la ~/.agents/skills/ — arrows pointing into ../ai-tools/ (i.e. ~/.agents/ai-tools/) mean "your repo, commit there." Anything else: leave alone unless asked.

Rules for edits

1. Edit via the canonical path, not the symlink. Open ~/.agents/ai-tools/src/skills/<name>/SKILL.md — never ~/.agents/skills/<name>/SKILL.md. Both resolve to the same inode, but committing from the canonical path keeps git status legible.
2. New tracked skill? Scaffold under src/skills/<name>/, then run ./scripts/link-skill.sh <name> from the repo. That creates the symlink in ~/.agents/skills/.
3. Product-specific skill? (description names the product — aviator-agent, etc.) Goes to that project's .agents/skills/<name>/, committed to the project repo. Not ai-tools.
4. Plugin / bundled / stock artifacts — do not edit, do not migrate. If the user wants a tweaked version, fork it into src/skills/<name>-<variant>/ with a new name.
5. Commit in the right repo. After editing:
   • src/skills/..., src/agents/..., src/scripts/... → commit + push in ~/.agents/ai-tools
   • <project>/.agents/skills/... or .agents/agents/... → commit in the project repo
6. Never edit anything under ~/.claude/plugins/ — that's marketplace-managed. If the user wants to customize a plugin skill, copy it into src/skills/ under a new name.

Race-condition note when migrating

If another agent is actively writing to ~/.agents/skills/<name>/, using link-skill.sh <name> --migrate (cp+rm+ln) does the right thing: once the symlink is in place, subsequent writes flow through to the repo copy. But any in-flight write that was already open when rm ran may be lost. Verify file integrity after a migration on active content.

Self-modification after non-trivial sessions

At end of session, if you produced a durable, sourced lesson (community-consensus or higher with a real citation, or direct session observation), prepare a proposal and surface it to the user — don't write substantive changes silently. The proposal names the destination, shows the diff, cites the source, and gives a one-line rationale. Write only after explicit approval. Minor improvements — typos, formatting, refreshed timestamps next to unchanged entries, dead-link updates, obvious cross-references that don't change any stated claim — can be applied autonomously. The dividing line is rule 8 of references/self-modification.md: does this edit change what the library claims? If yes → propose. If no (cosmetic / maintenance) → apply.

Full ruleset — citation gate, six-question trigger checklist, routing rule, conflict resolution, strike-through corrections, forbidden writes, user-approval gate — lives in references/self-modification.md. That file is general guidance covering the self-modification pattern for any prompt artifact (skills, subagents, CLAUDE.md, commands); this skill follows it for itself. No lessons.md, no journals, no ~/.agents/memory/ writes, no last_refresh bumps from manual edits, no silent substantive writes even when Edit is available.

Advising other artifacts on self-modification

When a user asks "should my skill / subagent / CLAUDE.md become self-modifying?" or "how do I make X remember what it learns?":

1. Check fit first. Not every artifact should self-modify. references/self-modification.md → "When the pattern fits" has the decision criteria. Skills with research-backed libraries: yes. Stateless templates, MCP wrappers, one-shot commands: no.
2. Verify prerequisites. Structured library, citation legend, topic map, user-preferences destination. If any is missing, fix that first — don't bolt self-modification on top of unstructured references.
3. Authority is proposal-for-substantive, autonomous-for-minor. Per rule 8, substantive edits (new knowledge, claim changes, re-routes, tag changes) require a visible proposal and explicit approval. Minor edits (typo fixes, formatting, refreshed timestamps, obvious cross-references) may be applied autonomously. The dividing line is claim-changing vs cosmetic/maintenance. What varies by artifact is how the proposal is surfaced and what "apply on approval" looks like — see the authority decision matrix in self-modification.md. Plugin-managed files remain off-limits (fork first; then the fork follows the same rule).
4. Use the matching topic file for specifics. Skills → 02-skills.md → Self-modifying skills. Subagents → 03-subagents.md → Self-modifying subagents. CLAUDE.md / instructions → 07-project-organization.md → Self-modifying CLAUDE.md. Each topic file covers the artifact-specific trigger mechanics, proposal format, placement rules, and adoption checklist.
5. Diff proposed rules against the "Required rules" list. All eight rules must be present — a missing or overly-strict rule 8 is the failure mode that most commonly either decays into silent claim-rewrites or balloons into "ask the user to approve every typo." Don't let an artifact adopt a half-version of the pattern.

What this skill does NOT cover

• Debugging the user's own application code → Debugger / feature-dev / etc.
• Project-specific context (this codebase's architecture) → project CLAUDE.md.
• Skills or agents internal to a specific plugin — describe how plugins work, not the internals of every published plugin.