Emacs
Emacs work: running state + persistent config on disk. Prefer evidence in order: running instance; official manuals via info; local installed docs/source via rg; ecosystem corroboration via Grep.app, then gh. Avoid cloning Emacs unless explicitly needed.
Entry point
Cross-platform command:
uv run --script <skill-dir>/scripts/cli.py ...
Set <skill-dir> to this skill directory. Do not rely on shell sourcing, executable bits, or shebang dispatch.
Required reads
- Any persistent or live Emacs change → read
references/live-workflow.md for inspect, preview, persist, and verify.
- Querying faces, buffers, keys, features, or paths → read
references/common-queries.md for exact runtime query recipes.
Workflow
- Inspect runtime state first.
- Inspect relevant config files only as needed.
- Pick the right persistence target.
- Preview the intended change if a live preview is useful.
- Apply the persistent edit.
- Apply live when safe.
- Verify runtime state and file state.
- Call out restart requirements explicitly.
- Write the requested artifact if the user asked for one.
Default: inspect → preview → apply → verify.
Output discipline
- A requested report, note, patch file, or other artifact at a specific path MUST be created before finalizing.
- When a concrete deliverable is requested, do not stop at acknowledgement, plan, or partial progress.
- After writing the artifact, summarize the result briefly.
Runtime introspection
Default Emacs communication: uv run --script <skill-dir>/scripts/cli.py; it dispatches to scripts/emacsctl.py, avoids fragile shell quoting, and simplifies common checks.
Use raw emacsclient only when debugging the helper, the helper is unavailable, or a truly tiny one-off probe is simpler with no quoting risk.
Prefer helper subcommands over custom Elisp when they fit: ping, face, buffer, key, library, feature, reload-init, load.
Quick checks:
uv run --script <skill-dir>/scripts/cli.py ping
uv run --script <skill-dir>/scripts/cli.py face default
uv run --script <skill-dir>/scripts/cli.py buffer
uv run --script <skill-dir>/scripts/cli.py library use-package
uv run --script <skill-dir>/scripts/cli.py feature server
For reusable or multiline queries, prefer a temporary .el file plus eval-file.
Guardrails
- Do not trust memory alone for Emacs semantics; inspect runtime, docs, or source.
- Do not assume a config layout, package set, theme, keybinding scheme, or distro integration; inspect first.
- Do not claim a startup-only change is live when it only fully applies on restart.
- Do not leave persistent intent as a session-only tweak unless the user requested a temporary experiment.
- Package-manager writes require explicit user intent.
- Keep diffs small and modular; do not turn
init.el into a dump file.
- After reloading, verify final state with runtime queries.
- Prefer querying variables, faces, frame params, keymaps, loaded features, and buffer state over guessing.
- Prefer
uv run --script <skill-dir>/scripts/cli.py over raw emacsclient when the helper can express the same operation reliably.
- Be explicit about risk when live-evaluating changes in an already-running Emacs.
1---2name: emacs3description: Use when Emacs, Emacs Lisp, init.el, packages, keybindings, automation, or runtime state are involved.4license: AGPL-3.0-or-later5---67# Emacs89Emacs work: running state + persistent config on disk. Prefer evidence in order: running instance; official manuals via `info`; local installed docs/source via `rg`; ecosystem corroboration via Grep.app, then `gh`. Avoid cloning Emacs unless explicitly needed.1011## Entry point1213Cross-platform command:1415```text16uv run --script <skill-dir>/scripts/cli.py ...17```1819Set `<skill-dir>` to this skill directory. Do not rely on shell sourcing, executable bits, or shebang dispatch.2021## Required reads2223- Any persistent or live Emacs change → read `references/live-workflow.md` for inspect, preview, persist, and verify.24- Querying faces, buffers, keys, features, or paths → read `references/common-queries.md` for exact runtime query recipes.2526## Workflow27281. Inspect runtime state first.292. Inspect relevant config files only as needed.303. Pick the right persistence target.314. Preview the intended change if a live preview is useful.325. Apply the persistent edit.336. Apply live when safe.347. Verify runtime state and file state.358. Call out restart requirements explicitly.369. Write the requested artifact if the user asked for one.3738Default: inspect → preview → apply → verify.3940## Output discipline4142- A requested report, note, patch file, or other artifact at a specific path MUST be created before finalizing.43- When a concrete deliverable is requested, do not stop at acknowledgement, plan, or partial progress.44- After writing the artifact, summarize the result briefly.4546## Runtime introspection4748Default Emacs communication: `uv run --script <skill-dir>/scripts/cli.py`; it dispatches to `scripts/emacsctl.py`, avoids fragile shell quoting, and simplifies common checks.4950Use raw `emacsclient` only when debugging the helper, the helper is unavailable, or a truly tiny one-off probe is simpler with no quoting risk.5152Prefer helper subcommands over custom Elisp when they fit: `ping`, `face`, `buffer`, `key`, `library`, `feature`, `reload-init`, `load`.5354Quick checks:5556```bash57uv run --script <skill-dir>/scripts/cli.py ping58uv run --script <skill-dir>/scripts/cli.py face default59uv run --script <skill-dir>/scripts/cli.py buffer60uv run --script <skill-dir>/scripts/cli.py library use-package61uv run --script <skill-dir>/scripts/cli.py feature server62```6364For reusable or multiline queries, prefer a temporary `.el` file plus `eval-file`.6566## Guardrails6768- Do not trust memory alone for Emacs semantics; inspect runtime, docs, or source.69- Do not assume a config layout, package set, theme, keybinding scheme, or distro integration; inspect first.70- Do not claim a startup-only change is live when it only fully applies on restart.71- Do not leave persistent intent as a session-only tweak unless the user requested a temporary experiment.72- Package-manager writes require explicit user intent.73- Keep diffs small and modular; do not turn `init.el` into a dump file.74- After reloading, verify final state with runtime queries.75- Prefer querying variables, faces, frame params, keymaps, loaded features, and buffer state over guessing.76- Prefer `uv run --script <skill-dir>/scripts/cli.py` over raw `emacsclient` when the helper can express the same operation reliably.77- Be explicit about risk when live-evaluating changes in an already-running Emacs.
anntnzrb