Add Trilium-specific Claude Code skills + fix CLAUDE.md path-rot

[eliandoran]

Summary

A repo-wide audit for ways to improve AI-assistant capabilities (Claude Code / Copilot) surfaced two things: our always-loaded instruction files had rotted, and several recurring, footgun-dense workflows had no captured guidance. This PR fixes the docs and adds seven Trilium-specific custom skills.

1. Fix stale paths in CLAUDE.md + .github/copilot-instructions.md

Server services were relocated apps/server/ → packages/trilium-core/, but the instruction files still cited the old paths. Verified dead and corrected: the DB-migration recipe (it described creating apps/server/src/migrations/*.sql — a path that no longer exists; real migrations are the descending MIGRATIONS array in packages/trilium-core/src/migrations/migrations.ts), schema.sql, options_init, the options route, hidden_subtree, ws, and cls.

2. Seven new skills (.claude/skills/)

Each is footgun-first, carries on-demand reference files, and (where useful) a runnable script:

Skill	Covers
evolving-the-data-model	DB migrations + Becca entity fields; the hashedProperties cross-instance sync-hash hazard; migration/spec templates
building-client-ui	the Preact-hooks model — which froca-reactive hook for which job + the loadResults filter each wires; Modal/LazyDialog wiring
adding-llm-mcp-tools	tools exposed to both chat and MCP; why execute must be sync (NotAPromise guard); mutates→transaction; spec harness
adding-internal-api-route	core-shared (runs under WASM) vs server-only; the apiRoute sync-transactional trap; implicit return conventions; CoreApiTester
electron-desktop-bridge	the contextBridge wiring across 7 handler modules; crash-safety; renderer-input validation. Ships scripts/ipc-parity.mjs
cutting-a-release	the two divergent version scripts; the CI gate that checks only 5 of 8 files; release-notes path; RELEASE_PAT. Ships scripts/preflight-release-check.mts
trilium-ckeditor5-integration	wiring a CKEditor plugin into Trilium's bundle (the 5 plugin arrays, slash/translation wiring, persistence pipeline, the real GPL+webdriverio test harness)

3. Refresh three existing skills

• writing-unit-tests — correct the stale "@vitest/browser unconfigured" line (it is configured), add a browser-mode row + a "core specs run twice (server + standalone WASM)" footgun.
• analyzing-coverage — add the standalone (sqlite-wasm) suite as a third coverage source.
• translating-locales — distinguish filling vs registering a locale; replace hardcoded coverage figures with measure-first.

How it was verified

Every skill was authored from a spec verified against live code, then reviewed by a second pass that spot-checked citations and ran the scripts (ipc-parity.mjs exits 0; preflight-release-check.mts passes 5 scenarios). The review caught and fixed real citation drift (e.g. a false migration example, inflated hook counts).

Not included / follow-ups

• The remaining ranked skills (llm-providers-and-streaming has a ready spec; e2e, etapi, standalone-providers, note-types, hidden-subtree, docs, options, packaging, search-modifier).
• Merging the three upstream ckeditor5-* draft skills (this PR's trilium-ckeditor5-integration is their Trilium companion).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive suite of Claude "skills" (developer guides, reference documents, templates, and helper scripts) under .claude/skills/ to document and streamline development workflows in Trilium. These cover key areas such as adding internal API routes, LLM/MCP tools, building client UI, release management, Electron desktop bridge, database migrations, and CKEditor 5 integration. It also aligns CLAUDE.md and .github/copilot-instructions.md with these updated guidelines. The feedback on the ipc-parity.mjs script is constructive, suggesting a regex improvement to robustly support asynchronous setup functions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The regex currently expects synchronous functions (export function ...). If any setup or registration function is made asynchronous in the future (e.g., export async function setupX()), it will be silently skipped by this script. Supporting optional async makes the parser more robust.

Suggested change

	for (const fn of matchAll(
	text,
	/export\s+function\s+((?:setup|register)\w+)\s*\(/g,
	(m) => m[1]
	)) {
	for (const fn of matchAll(
	text,
	/export\s+(?:async\s+)?function\s+((?:setup|register)\w+)\s*\(/g,
	(m) => m[1]
	)) {

[greptile-apps]

Greptile Summary

This PR fixes rotted paths in CLAUDE.md and .github/copilot-instructions.md (server services relocated from apps/server/ to packages/trilium-core/), then adds seven new Trilium-specific Claude Code skills covering migrations, client UI, LLM/MCP tools, API routes, Electron IPC, releases, and CKEditor integration, while refreshing three existing skills.

• Path fixes: migrations, schema, WebSocket, options, hidden-subtree, and CLS paths are all updated to their current packages/trilium-core/src/ locations; each fix was verified against the live codebase.
• Seven new skills: each is footgun-first, cites real file:line anchors, and ships runnable scripts where useful (preflight-release-check.mts validates all 9 package.jsons the CI gate misses; ipc-parity.mjs diffs the Electron bridge end-to-end).
• Three refreshed skills: writing-unit-tests corrects the stale "browser mode unconfigured" claim and documents the core-specs-run-twice footgun; analyzing-coverage adds the standalone WASM suite; translating-locales separates filling vs. registering a locale.

Confidence Score: 5/5

All changes are documentation only — no runnable application code was modified. The two bundled scripts are developer tooling (pre-flight checks and IPC parity analysis) that run outside the application. Safe to merge.

Every corrected path was verified against the live repo. The seven new skills cite real file:line anchors and were validated before submission. The bundled scripts contain no application logic. The only open items are stale paths in copilot-instructions.md sections untouched by this PR, which a follow-up can clean up.

.github/copilot-instructions.md still has a handful of stale apps/server/src/ references in sections not touched by this PR (becca, events, search, Shaca on line 14).

Important Files Changed

Filename	Overview
CLAUDE.md	Corrects stale paths across migrations, schema, options, hidden-subtree, websocket, and electron sections; adds a Custom Skills section. All verified path changes look accurate.
.github/copilot-instructions.md	Fixes REST API, WebSocket, migrations, schema, and options paths. Several stale apps/server/src/ references remain in untouched sections (becca, events, search, Shaca on line 14).
.claude/skills/evolving-the-data-model/SKILL.md	Comprehensive migration skill covering the MIGRATIONS array, schema.sql parity, becca_loader alignment, and sync-hash hazard; frontmatter CLAUDE.md is WRONG claim is now stale since CLAUDE.md was fixed in this same PR.
.claude/skills/cutting-a-release/SKILL.md	Well-verified release recipe covering the two version scripts, CI gate gaps, release-notes doubled path, rc/beta labeling, and PAT requirements. Matches what update-version.ts and release.yml actually do.
.claude/skills/electron-desktop-bridge/SKILL.md	Accurate 5-place wiring recipe for the contextBridge IPC, transport decision table, module map, and crash-safety guidance. Correctly identifies preload.spec.ts co-location and the dead-module-until-setup footgun.
.claude/skills/building-client-ui/SKILL.md	New skill covering froca-reactive hooks, entitiesReloaded filter taxonomy, reusable component rules, and the LazyDialog 5-step registration. Hook table and reload-predicate distinctions are accurate.
.claude/skills/cutting-a-release/scripts/preflight-release-check.mts	Pre-flight script checks all 9 package.jsons (verified against update-version.ts), confirms release-notes doubled path, and warns on rc/beta labeling. Logic is correct and the CI_GATE_FILES subset matches the actual check-version-consistency.ts.
.claude/skills/electron-desktop-bridge/scripts/ipc-parity.mjs	Direction-aware IPC parity checker validating preload/ipcMain sync across 5 finding classes. Repo-root detection uses both path traversal and package.json name guard; regex-based static analysis is reasonable for this use case.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Developer task] --> B{Which skill?}
    B --> C[evolving-the-data-model]
    B --> D[building-client-ui]
    B --> E[adding-llm-mcp-tools]
    B --> F[adding-internal-api-route]
    B --> G[electron-desktop-bridge]
    B --> H[cutting-a-release]
    B --> I[trilium-ckeditor5-integration]
    C --> C1[MIGRATIONS array / schema.sql parity / sync-hash hazard]
    D --> D1[54 froca-reactive hooks / entitiesReloaded filters / LazyDialog]
    E --> E1[NotAPromise guard / mutates=true / allToolRegistries]
    F --> F1[core-shared ~140 routes / apiRoute sync trap]
    G --> G1[5-place wiring recipe / transport table / ipc-parity.mjs]
    H --> H1[2 version scripts / CI gate 5 of 9 / preflight-release-check.mts]
    I --> I1[5 plugin arrays / slash wiring / GPL webdriverio harness]

Loading

_{Reviews (3): Last reviewed commit: "docs: document the chore(skills) commit ..." | Re-trigger Greptile}

[codecov]

Bundle Report

Bundle size has no change ✅

Affected Assets, Files, and Routes:

view changes for bundle: client-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
src/dist-*.js	6 bytes	63 bytes	10.53% ⚠️
src/dist-*.js	-6 bytes	57 bytes	-9.52%
src/dist-*.js	7 bytes	63 bytes	12.5% ⚠️
src/dist-*.js	-7 bytes	56 bytes	-11.11%
src/src-*.js	-105 bytes	104 bytes	-50.24%
src/src-*.js	105 bytes	209 bytes	100.96% ⚠️