Skills on Lesstruct

Mon, 01 Jan 0001 00:00:00 +0000

Development vs Production Mode#

Lesstruct’s plugin system supports two modes, toggled by the same DEV_MODE env var used by the admin SPA.

Production mode (default)#

When DEV_MODE is unset, false, or any value other than the string "true" (the runtime uses getEnvBool, which is permissive about the exact spelling), the plugin system loads all .wasm files in plugins/ once at startup. To apply changes, restart the server.

This is the recommended mode for any non-development environment.

Mon, 01 Jan 0001 00:00:00 +0000

Content Transform Plugin#

A Lesstruct plugin that transforms content before it is saved by uppercasing the title.

Prerequisites#

TinyGo 0.28+

Build#

1

tinygo build -o content-transform.wasm -target=wasi main.go

Install#

Copy the compiled WASM file to the Lesstruct plugins directory:

1

cp content-transform.wasm <lesstruct-project>/plugins/

Expected Behavior#

When content is saved, the plugin intercepts the before_save hook and uppercases the "title" field value. For example:

Input: {"title":"my blog post", "content":"..."}
Output: {"title":"MY BLOG POST", "content":"..."}

Mon, 01 Jan 0001 00:00:00 +0000

Hello World Plugin#

A minimal Lesstruct plugin that responds when loaded by the plugin system.

Prerequisites#

TinyGo 0.28+

Build#

1

tinygo build -o hello-world.wasm -target=wasi main.go

Install#

Copy the compiled WASM file to the Lesstruct plugins directory:

1

cp hello-world.wasm <lesstruct-project>/plugins/

Expected Behavior#

When Lesstruct starts, it loads the plugin and calls hook_on_plugin_loaded. The plugin returns a JSON response:

1

{"status":"loaded","plugin":"hello-world","input_size":"..."}

Mon, 01 Jan 0001 00:00:00 +0000

Validation Plugin#

A Lesstruct plugin that validates content before it is saved by rejecting empty titles.

Prerequisites#

TinyGo 0.28+

Build#

1

tinygo build -o validation.wasm -target=wasi main.go

Install#

Copy the compiled WASM file to the Lesstruct plugins directory:

1

cp validation.wasm <lesstruct-project>/plugins/

Expected Behavior#

When content is saved, the plugin intercepts the before_save hook and checks if the "title" field is empty.

If the title is empty, the plugin returns an error response:

1

{"error":"validation failed","message":"title must not be empty"}

If the title is not empty, the original content passes through unchanged.

Mon, 01 Jan 0001 00:00:00 +0000

Install Paths#

Path note. The exact skill directory location depends on the agent. The patterns below are based on common conventions; if your agent uses a different path, adjust accordingly. The README.md of this skill is the canonical install guide; this file is a quick reference.

Claude Code#

1
2


# Copy the skill into Claude Code's skill directory.
cp -r lesstruct-plugin-development ~/.claude/skills/lesstruct-plugin-development

Claude Code loads skills from ~/.claude/skills/ by default. If you have configured a custom path, substitute it.

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Capabilities#

Snapshot notice. This is the user-facing snapshot of the Lesstruct plugin capabilities reference, bundled with the lesstruct-plugin-development skill so the skill is self-contained. The canonical, developer-facing version lives in the Lesstruct repository at docs/plugin-capabilities.md and references source-tree paths; this version is rewritten for someone with a binary Lesstruct install and a plugins/ directory.

If you have a newer Lesstruct release, re-export this file from the repo to refresh the snapshot.

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Pre-Flight Checklist#

Use this checklist to audit a plugin before declaring it ready. Each item is a hard pass / fail.

File layout#

Plugin file is <name>.wasm in plugins/.
Optional <name>.manifest is in the same directory as the .wasm.
Plugin filename (without extension) and the manifest’s name field match. The host does not enforce this today, but matching them is good hygiene.

Hooks#

Plugin exports at least one of the three currently-invoked hooks: hook_before_save, hook_after_create, hook_after_publish.
Plugin does not rely on hook_on_plugin_loaded or hook_before_delete. Both are defined in the host but not currently invoked. Plugins that only export one of these will load but never fire.
Each hook’s result is a JSON object containing (at most) customFields for mutation. The host reads only customFields back; other fields in the result are ignored.
__hook_result_len is exported only if the result length differs from the input length. The export is optional; the host uses inputLen as the result length when the export is missing.

Manifest#

name is set and non-empty.
version is set and non-empty.
capabilities.http is set to a list of URL patterns if the plugin uses http_get or http_post.
capabilities.database is set to a list of read|write:content|media|users permissions if the plugin uses db_query or db_exec.
URL patterns use trailing * only (no regex, no ?).
URL patterns are ordered so the most specific match comes first (the first match wins).

Host function calls#

If the plugin uses http_get or http_post, the manifest’s http patterns cover the actual URLs the plugin will request.
If the plugin uses db_query or db_exec, the manifest’s database permissions cover the actual table names in the queries (and the actual operation: db_query is always read, db_exec is always write).
Every SQL query is a single explicit SELECT / INSERT / UPDATE / DELETE statement. No CTEs, no subqueries, no comments, no quoted identifiers, no multi-statement queries.
The plugin reads each host function’s result from offset 4096 before invoking the next host function. All four data host functions share the same result offset.

Build#

Compiled with tinygo build -target=wasi (Go), cargo build --target wasm32-wasip1 (Rust), or clang --target=wasm32-wasi (C/C++).
Compiled .wasm is well under 64 MB (typical TinyGo plugin: < 1 MB).
For Go plugins that use host functions, the //go:wasmimport block from references/host-function-imports.go.txt is copied into the plugin’s main.go.

Deployment#

Lesstruct was restarted after the last plugins/ change (unless DEV_MODE=true is set; in that case, the watcher picks up new .wasm files automatically).
The .wasm is the top-level file in plugins/. Subdirectories are not watched.

Smoke test#

Run the smoke test from SKILL.md Step 8 and confirm the relevant hook fires and any customFields modification is reflected in the saved item.
For host function calls, check the Lesstruct log for “blocked” messages. If the call was permitted, no log line is produced (audit logging is partial); use log_info from the plugin to record what it did.

Documentation#

A plugins/<name>.README records the Lesstruct version the plugin was authored against, the hooks it uses, and the capabilities declared in the manifest.

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Development Guide#

Snapshot notice. This is the user-facing snapshot of the Lesstruct plugin development guide, bundled with the lesstruct-plugin-development skill so the skill is self-contained. The canonical, developer-facing version lives in the Lesstruct repository at docs/plugin-development.md and references source-tree paths; this version is rewritten for someone with a binary Lesstruct install and a plugins/ directory.

If you have a newer Lesstruct release, re-export this file from the repo to refresh the snapshot.

Mon, 01 Jan 0001 00:00:00 +0000

Install Paths#

Path note. The exact skill directory location depends on the agent. The patterns below are based on common conventions; if your agent uses a different path, adjust accordingly. The README.md of this skill is the canonical install guide; this file is a quick reference.

Claude Code#

1
2


# Copy the skill into Claude Code's skill directory.
cp -r lesstruct-theme-development ~/.claude/skills/lesstruct-theme-development

Claude Code loads skills from ~/.claude/skills/ by default. If you have configured a custom path, substitute it.

Mon, 01 Jan 0001 00:00:00 +0000

Page Render Smoke Test#

This is a manual smoke test for a Lesstruct theme. Run it after every change to themes/<name>/ and after every Lesstruct upgrade. The skill does not have access to the Lesstruct source, so this test must be run by you, against your running install, in a browser or with curl.

Setup#

Confirm THEME_DIR is set and Lesstruct is running.
Confirm at least one post exists (the smoke test uses /<slug>).
Confirm at least one user with author profile exists (for the author page).
Confirm at least one post has at least one tag (for the tag page).
Replace <slug>, <username>, and <tag> in the URLs below with values from your install.

Page-by-page test#

For each URL: load it in a browser (or curl it), then check the column on the right. The “Smoke signal” column is the smallest signal that the page rendered and your theme took effect.

Mon, 01 Jan 0001 00:00:00 +0000

Theme Audit Checklist#

Use this checklist to audit a themes/<name>/ directory before declaring a theme ready. Each item is a hard pass / fail.

Environment#

THEME_DIR is set in .env or the environment the Lesstruct process runs in (not only in a shell session that has since closed).
THEME_DIR resolves to an existing directory.
Lesstruct was restarted after the most recent THEME_DIR change.
The theme directory has a static/ and a templates/ subdirectory (even if empty).

CSS (`static/style.css`)#

static/style.css is valid CSS (run it through a linter).
static/style.css does not reference style.src.css (the source file is not served; only the minified style.css is).
Every CSS variable the default theme defines is still defined in the override (or in a parent file the override loads). The full set is in the CSS Variable Reference.
@import URLs (fonts, third-party CSS) resolve.

Layout template (`templates/layout.html`)#

File defines {{define "layout"}}…{{end}} exactly once.
The HTML element has lang="{{.Lang}}".
<title>{{.PageTitle}}</title> is present.
<link rel="stylesheet" href="/static/style.css"> is present.
<main>…{{template "body" .}}…</main> is present.
The Open Graph <meta> tags are present (otherwise share previews break).
<script src="/static/nav-auth.js"></script> and <script src="/static/search.js"></script> are present (otherwise the nav login/logout toggle and search dropdown break).

Page templates (any `templates/<page>.html` you ship)#

The template defines {{define "body"}}…{{end}} exactly once.
The template uses the data fields listed in Template Data Fields by their documented names (.Title, .PageTitle, etc.).

JavaScript DOM contract#

If you override static/comments.js:

Mon, 01 Jan 0001 00:00:00 +0000

Theme Development Guide#

Snapshot notice. This is the user-facing snapshot of the Lesstruct theme development guide, bundled with the lesstruct-theme-development skill so the skill is self-contained. The canonical, developer-facing version lives in the Lesstruct repository at docs/theme-development.md and references source-tree paths; this version is rewritten for someone with a binary Lesstruct install and a themes/<name>/ directory.

If you have a newer Lesstruct release, re-export this file from the repo to refresh the snapshot.

Skills on Lesstruct

Development vs Production Mode#

Production mode (default)#

Content Transform Plugin#

Prerequisites#

Build#

Install#

Expected Behavior#

Hello World Plugin#

Prerequisites#

Build#

Install#

Expected Behavior#

Validation Plugin#

Prerequisites#

Build#

Install#

Expected Behavior#

Install Paths#

Claude Code#

Plugin Capabilities#

Plugin Pre-Flight Checklist#

File layout#

Hooks#

Manifest#

Host function calls#

Build#

Deployment#

Smoke test#

Documentation#

Plugin Development Guide#

Install Paths#

Claude Code#

Page Render Smoke Test#

Setup#

Page-by-page test#

Theme Audit Checklist#

Environment#

CSS (static/style.css)#

Layout template (templates/layout.html)#

Page templates (any templates/<page>.html you ship)#

JavaScript DOM contract#

Theme Development Guide#

CSS (`static/style.css`)#

Layout template (`templates/layout.html`)#

Page templates (any `templates/<page>.html` you ship)#