0xrichardh/agent-skills

Overview

This skill provides a practical, example-driven guide to building, debugging, and deploying Logseq plugins using TypeScript and the @logseq/libs SDK. It focuses on manifest setup, lifecycle hooks, Editor/App/DB/UI API usage, and recommended development workflows. Use it to get from scaffold to a working plugin with predictable behavior inside Logseq's iframe sandbox.

How this skill works

The skill explains how a plugin runs inside a sandboxed iframe and communicates with the main app via RPC, and how to initialize your code with logseq.ready(main). It covers manifest requirements, installing @logseq/libs, bundling with Vite or similar, and loading an unpacked plugin in developer mode. It also walks through using the Editor, App, DB, and UI APIs for read/write operations, commands, queries, and theme-aware UI injections.

When to use it

• Create a new Logseq plugin from scratch (Vanilla TS or React + Vite).
• Implement editor features: slash commands, block insertion, batch edits.
• Integrate with Logseq DB: datascript queries and programmatic page/block queries.
• Build UI inside Logseq: provideUI, main UI, and theme-aware components.
• Debug, refactor, or optimize an existing plugin for stability and performance.

Best practices

• Declare a clear logseq field in package.json and use logseq.ready(main) for initialization.
• Use @logseq/libs types in TypeScript for safer API usage and autocompletion.
• Keep heavy work off the main thread; batch DB writes and debounce editor operations.
• Use Logseq CSS variables for theming so UI matches user themes and dark mode.
• Keep RPC interactions minimal and validate responses; handle plugin unload/cleanup in lifecycle hooks.

Example use cases

• Add a slash command that inserts templated content into the current page and preserves cursor position.
• Create a sidebar React app that queries the DB for tasks and provides bulk-complete actions.
• Build a small visualization using provideUI that respects Logseq theme variables and updates on DB changes.
• Refactor a plugin to replace direct DOM access with provideUI and SDK APIs for better compatibility.
• Debug intermittent errors by adding lifecycle logs, catching rejected promises, and testing in unpacked plugin developer mode.