Logseq Plugin SDK

What it does

When your agent uses it

• The task involves writing plugin entry code
• Registering slash/command/UI items
• ProvideUI/provideStyle/provideModel
• Settings schema

Example prompts

• “/logseq-plugin-sdk”

Requirements

• Node.js

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

1. 1Always await logseq.ready(main) before touching any API. Most SDK calls are async RPC over postMessage.
2. 2Detect graph mode before using DB-only APIs: await logseq.App.checkCurrentIsDbGraph(). IBatchBlock.properties is not supported for DB…
3. 3Clean up listeners in logseq.beforeunload (collect the off functions returned by every onXxx hook).
4. 4Batch mutations (Editor.insertBatchBlock) and debounce DB.onChanged / onBlockChanged handlers — they fire on every keystroke.
5. 5Prefer CSS variables (--ls-primary-text-color, --ls-primary-background-color, --ls-border-color, …) over hard-coded colors so plugins…
6. 6Unique plugin id in package.json > logseq.id; keep it lowercase-kebab. main/entry must point at a built HTML file.
7. 7Experimental APIs (logseq.Experiments.*) are unstable — only use when no stable API exists and document the reason.
8. 8Idents are identity. For built-in or cross-graph stable references, use idents (:logseq.property/created-at, :plugin.property./) instead…

What it can do on your machine

Read from SKILL.md and the folder at commit 22a29b3. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (JavaScript, from the files we listed), which the agent can run.

  Shell commands in SKILL.md call:

  • yarn
  • npm

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • github.com
  • plugins-doc.logseq.com
  • discord.gg

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Logseq Plugin SDK loads about 2.3k tokens when it runs. Until then it costs about 110 tokens; SKILL.md has 752 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~110

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from logseq/logseq at commit 22a29b3, republished under its AGPL-3.0 licence (© logseq). 752 words, ~2,288 tokens.

name

logseq-plugin-sdk

description

Build, debug, or review Logseq plugins with the `@logseq/libs` SDK (TypeScript/JavaScript, iframe/shadow sandboxed). Use when the task involves writing plugin entry code, registering slash/command/UI items, provideUI/provideStyle/provideModel, settings schema, macro renderers, DB-graph properties & tags, Datascript/DSL queries, experimental APIs, theme plugins, or the `logseq/*` CLJS facade generated under this package.

import '@logseq/libs'

const offHooks: Array<() => void> = []

async function main() {
  logseq.useSettingsSchema([
    { key: 'enabled', type: 'boolean', default: true, title: 'Enabled', description: '' },
  ])

  logseq.Editor.registerSlashCommand('My Command', async () => {
    await logseq.Editor.insertAtEditingCursor('Hello from my plugin!')
  })

  offHooks.push(
    logseq.DB.onChanged(({ blocks }) => {
      // debounce in real code
    }),
  )

  logseq.beforeunload(async () => {
    offHooks.forEach((off) => off())
  })
}

logseq.ready(main).catch(console.error)

© logseq, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 57 other files (scripts) in libs of logseq/logseq.

• SKILL.md
• .gitignore
• .npmignore
• .prettierrc.js
• CHANGELOG.md
• README.md
• babel.config.json
• cljs-sdk/.gitignore
• cljs-sdk/LICENSE
• cljs-sdk/bb.edn
• cljs-sdk/build.clj
• cljs-sdk/deps.edn
• cljs-sdk/package.json
• cljs-sdk/pnpm-lock.yaml
• cljs-sdk/src/com/logseq/app.cljs
• cljs-sdk/src/com/logseq/assets.cljs
• cljs-sdk/src/com/logseq/commands.cljs
• … and 41 more

Open the folder on GitHubat commit 22a29b3