how-to

Use the LLM Skill and Plugin

Install the skill when an LLM agent needs the same flavor detection, diagnostics, symbols, folds, hovers, completions, and structured-profile evidence that the editor uses.

When to use it

The skill packages a runtime-specific Flavor Grenade LSP executable with wrapper commands that return stable JSON. Agents can ask the wrapper for Markdown flavor, configuration evidence, diagnostics, document structure, completions, references, and structured variants before editing a file.

Use it for Claude, Codex, or another compatible skill/plugin host when Markdown edits depend on flavor behavior. The wrapper is not a Markdown renderer and does not execute code blocks, MDX JavaScript, R chunks, Pandoc filters, or remote references.

Steps

Repository marketplace metadata points at the plugin-local skill source. Compatible installers can discover `flavorgrenade-lsp` from this repository and install the matching skill/plugin into the agent environment.

For installers that implement the `npx skill` command shape, the portable install target is:

If your installer uses a different command shape, point it at `alisonaquinas/flavor-grenade-lsp` and choose the `flavorgrenade-lsp` skill. The repository includes separate marketplace metadata for portable skills, Claude plugin discovery, and Codex plugin discovery so host-specific installers can use their own catalog format.

npx skill install alisonaquinas/flavor-grenade-lsp --skill flavorgrenade-lsp
npx skill list alisonaquinas/flavor-grenade-lsp

Expected result

After installation, run the wrapper's verification command from the installed skill directory. Verification checks the manifest, selected runtime target, digest, optional signature bundle, and a basic LSP handshake.

If verification fails, reinstall the skill or choose an artifact for the current runtime target. Do not ask the agent to continue with flavor-sensitive edits when executable digest verification fails.

node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs verify-install --json

Common failure mode

The common failure mode is letting an agent guess Markdown behavior or parse Flavor Grenade configuration by itself. Ask the agent to run `detect` before flavor-sensitive edits and `analyze` before broad rewrites.

The wrapper reports the effective base flavor, structured profiles such as Keep a Changelog or MADR, configuration source, inference evidence, diagnostics, symbols, folds, hovers, completions, and boundaries.

For broad workspace commands, give the wrapper an explicit file budget and path filter. `--include` and `--exclude` accept glob selectors, `--max-files` caps the number of Markdown files collected, and `--max-bytes` skips oversized Markdown files before the agent reads them.

Treat wrapper output as the source of truth. Do not copy one file's flavor decision to another directory without evidence, and do not reinterpret `.flavor-grenade.*` or `.editorconfig` configuration manually.

node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs detect README.md --json
node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs analyze docs --json
node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs diagnostics CHANGELOG.md --json
node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs symbols docs/adr/0001-record.md --json

node skills/flavorgrenade-lsp/wrappers/flavorgrenade.mjs analyze docs --include "**/*.md" --exclude "private/**" --max-files 200 --max-bytes 262144 --json

Choose the LSP package instead when building an editor client

Use the skill/plugin for agent workflows. Use the npm language-server package when you are wiring an editor, test harness, or direct LSP client that will launch `flavor-grenade-lsp` over stdio and send a `rootUri`.

npm install --save-dev flavor-grenade-lsp
npx flavor-grenade-lsp