<purpose> Provide comprehensive patterns for Emacs Lisp, configuration management, package systems, and major packages including Magit and LSP integration. For org-mode patterns, see org-ecosystem skill. </purpose>

<elisp_fundamentals> <concept name="basic_syntax"> <description>S-expressions as code and data (homoiconicity). Prefix notation for all operations.</description> </concept>

<concept name="data_types"> <description>Emacs Lisp data types: symbol, cons cell, list, vector, hash-table, string, number</description> <example> ;; symbol: Named objects 'foo :keyword

code

  ;; cons_cell: Pair
  (cons 1 2) ; => (1 . 2)

  ;; list: Linked cons cells
  '(1 2 3)

  ;; vector: Fixed-size array
  [1 2 3]

  ;; hash-table: Key-value store
  (make-hash-table)

  ;; string: Text
  "hello"

  ;; number: Integer or float
  42
  3.14
</example>

</concept> <pattern name="defun"> <description>Define functions with defun</description> <example> (defun my-function (arg1 arg2) "Docstring describing the function." (+ arg1 arg2)) </example> </pattern> <pattern name="let_binding"> <description>Local variable binding with let and let*</description> <example> (let ((x 1) (y 2)) (+ x y))

code

  (let\* ((x 1)
          (y (+ x 1))) ; y can reference x
    y)
</example>

</pattern> <pattern name="conditionals"> <description>Conditional forms: if, when, unless, cond, pcase</description> <example> (if condition then-form else-form)

code

  (when condition
    body-forms...)

  (unless condition
    body-forms...)

  (cond
    (condition1 result1)
    (condition2 result2)
    (t default-result))

  (pcase value
    ('symbol (handle-symbol))
    ((pred stringp) (handle-string))
    (\_ (handle-default)))
</example>

</pattern> <pattern name="iteration"> <description>Iteration patterns: dolist, dotimes, cl-loop, seq functions</description> <example> (dolist (item list) (process item))

code

  (dotimes (i 10)
    (process i))

  (cl-loop for item in list
           collect (transform item))

  (seq-map #'transform sequence)
  (seq-filter #'predicate sequence)
  (seq-reduce #'fn sequence initial)
</example>

</pattern> <pattern name="lambda"> <description>Anonymous functions with lambda</description> <example> (lambda (x) (* x 2))

code

  (mapcar (lambda (x) (\* x 2)) '(1 2 3))

  ;; Short form (Emacs 28+)
  (mapcar (lambda (x) (+ x 1)) list)
</example>

</pattern> <pattern name="macros"> <description>Define macros with defmacro. Use backquote for templates, comma for evaluation</description> <example> (defmacro with-temp-message (msg &rest body) "Execute BODY with MSG displayed temporarily." `(let ((message-log-max nil)) (message "%s" ,msg) (unwind-protect (progn ,@body) (message nil)))) </example> </pattern> </elisp_fundamentals>

<configuration_patterns> <pattern name="init_el_structure"> <description>Modern init.el organization</description> <example> ;;; init.el --- Emacs configuration -*- lexical-binding: t; -_-

code

  ;;; Commentary:
  ;; Personal Emacs configuration

  ;;; Code:

  ;; Bootstrap package manager
  (require 'package)
  (setq package-archives
        '(("melpa" . "https://melpa.org/packages/")
          ("gnu" . "https://elpa.gnu.org/packages/")
          ("nongnu" . "https://elpa.nongnu.org/nongnu/")))
  (package-initialize)

  ;; Install use-package if not present
  (unless (package-installed-p 'use-package)
    (package-refresh-contents)
    (package-install 'use-package))

  (eval-when-compile
    (require 'use-package))

  ;; Configuration sections...

  (provide 'init)
  ;;; init.el ends here
</example>

</pattern> <pattern name="use_package"> <description>Declarative package configuration with use-package keywords</description> <decision_tree name="when_to_use"> <question>Does the package need lazy loading or declarative configuration?</question> <if_yes>Use use-package for clean, maintainable configuration</if_yes> <if_no>Use require for simple packages with no configuration needs</if_no> </decision_tree> <example> (use-package company :ensure t :defer t :hook (prog-mode . company-mode) :bind (:map company-active-map ("C-n" . company-select-next) ("C-p" . company-select-previous)) :custom (company-idle-delay 0.2) (company-minimum-prefix-length 2) :config (setq company-backends '(company-capf))) </example> <note> Keywords: - :ensure - Install package if not present - :defer - Lazy load (t or seconds) - :hook - Add to mode hooks - :bind - Define keybindings - :custom - Set customizable variables - :init - Run before package loads - :config - Run after package loads - :commands - Autoload commands - :after - Load after specified packages - :if/:when/:unless - Conditional loading </note> </pattern> <pattern name="keybinding"> <description>Key binding patterns: global-set-key, define-key, use-package :bind</description> <example> ;; Global keybinding (global-set-key (kbd "C-c l") #'org-store-link)

code

  ;; Mode-specific
  (define-key emacs-lisp-mode-map (kbd "C-c C-e") #'eval-last-sexp)

  ;; With use-package
  (use-package magit
    :bind (("C-x g" . magit-status)
           ("C-x M-g" . magit-dispatch)))

  ;; Keymap definition
  (defvar my-prefix-map (make-sparse-keymap)
    "Keymap for my custom commands.")
  (global-set-key (kbd "C-c m") my-prefix-map)
  (define-key my-prefix-map (kbd "f") #'find-file)
</example>

</pattern> <pattern name="hooks"> <description>Hook management with add-hook and use-package :hook</description> <example> ;; Add function to hook (add-hook 'prog-mode-hook #'display-line-numbers-mode)

code

  ;; Remove function from hook
  (remove-hook 'prog-mode-hook #'display-line-numbers-mode)

  ;; Lambda in hook (discouraged for removability)
  (add-hook 'after-save-hook
            (lambda () (message "Saved!")))

  ;; With use-package
  (use-package flycheck
    :hook (prog-mode . flycheck-mode))
</example>

</pattern> <pattern name="advice"> <description>Modify existing functions with advice-add and advice-remove</description> <example> (defun my-after-save-message (orig-fun &rest args) "Show message after save." (apply orig-fun args) (message "Buffer saved at %s" (current-time-string)))

code

  (advice-add 'save-buffer :around #'my-after-save-message)

  ;; Remove advice
  (advice-remove 'save-buffer #'my-after-save-message)
</example>

</pattern> <pattern name="custom_variables"> <description>Define customizable variables with defgroup and defcustom</description> <example> (defgroup my-package nil "My package customization." :group 'convenience :prefix "my-package-")

code

  (defcustom my-package-option t
    "Enable my-package option."
    :type 'boolean
    :group 'my-package)

  (defcustom my-package-list '("a" "b")
    "List of strings."
    :type '(repeat string)
    :group 'my-package)
</example>

</pattern> </configuration_patterns> <tools> <tool name="package.el"> <description>Built-in package manager for Emacs</description> <example> ;; Commands: ;; - package-install - Install a package ;; - package-delete - Remove a package ;; - package-refresh-contents - Update package list ;; - package-list-packages - Browse packages

code

  (require 'package)
  (setq package-archives
        '(("melpa" . "https://melpa.org/packages/")
          ("gnu" . "https://elpa.gnu.org/packages/")))
  (package-initialize)

  ;; Install a package
  (package-install 'magit)
</example>

</tool> <tool name="straight.el"> <description>Functional package manager with Git integration</description> <example> ;; Bootstrap (defvar bootstrap-version) (let ((bootstrap-file (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))) (unless (file-exists-p bootstrap-file) (with-current-buffer (url-retrieve-synchronously "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el") (goto-char (point-max)) (eval-print-last-sexp))) (load bootstrap-file nil 'nomessage))

code

  ;; Use with use-package
  (straight-use-package 'use-package)
  (setq straight-use-package-by-default t)

  ;; Install package
  (use-package magit
    :straight t)
</example>

</tool> <tool name="elpaca"> <description>Modern async package manager</description> <example> ;; Bootstrap (defvar elpaca-installer-version 0.7) (defvar elpaca-directory (expand-file-name "elpaca/" user-emacs-directory)) ;; ... (bootstrap code)

code

  ;; Use with use-package
  (elpaca elpaca-use-package
    (elpaca-use-package-mode))

  (use-package magit
    :ensure t)
</example>

</tool> </tools> <magit> <description>Git porcelain for Emacs</description> <pattern name="basic_usage"> <description>Basic Magit setup with use-package</description> <example> (use-package magit :ensure t :bind (("C-x g" . magit-status) ("C-x M-g" . magit-dispatch) ("C-c M-g" . magit-file-dispatch))) </example> </pattern> <pattern name="status_buffer"> <description>Magit status buffer keybindings</description> <example> ;; s - Stage file/hunk ;; u - Unstage file/hunk ;; c c - Commit ;; P p - Push ;; F p - Pull ;; b b - Checkout branch ;; b c - Create branch ;; l l - Log current branch ;; d d - Diff </example> </pattern> <pattern name="configuration"> <description>Magit configuration settings</description> <example> (setq magit-save-repository-buffers 'dontask) (setq magit-display-buffer-function #'magit-display-buffer-same-window-except-diff-v1) (setq magit-diff-refine-hunk 'all) </example> </pattern> <pattern name="forge"> <description>GitHub/GitLab integration with Forge</description> <example> (use-package forge :after magit :ensure t) </example> </pattern> </magit>

<lsp_integration> <decision_tree name="when_to_use"> <question>Do you need LSP features like completion, go-to-definition, and diagnostics?</question> <if_yes>Use eglot for built-in simplicity or lsp-mode for rich features</if_yes> <if_no>Use basic major modes without LSP overhead</if_no> </decision_tree>

<pattern name="eglot"> <description>Built-in LSP client (Emacs 29+)</description> <example> (use-package eglot :ensure nil ; built-in :hook ((python-mode . eglot-ensure) (typescript-mode . eglot-ensure) (rust-mode . eglot-ensure)) :config (setq eglot-autoshutdown t) (setq eglot-events-buffer-size 0))

code

  ;; Custom server configuration
  (add-to-list 'eglot-server-programs
               '(rust-mode . ("rust-analyzer")))
</example>

</pattern> <pattern name="lsp_mode"> <description>Feature-rich LSP client with lsp-mode and lsp-ui</description> <example> (use-package lsp-mode :ensure t :hook ((python-mode . lsp-deferred) (typescript-mode . lsp-deferred)) :commands (lsp lsp-deferred) :custom (lsp-keymap-prefix "C-c l") (lsp-idle-delay 0.5) (lsp-log-io nil) :config (lsp-enable-which-key-integration t))

code

  (use-package lsp-ui
    :ensure t
    :hook (lsp-mode . lsp-ui-mode)
    :custom
    (lsp-ui-doc-enable t)
    (lsp-ui-sideline-enable t))
</example>

</pattern> <pattern name="completion"> <description>LSP completion with corfu/company</description> <example> ;; With corfu (modern) (use-package corfu :ensure t :custom (corfu-auto t) (corfu-cycle t) :init (global-corfu-mode))

code

  ;; With company (traditional)
  (use-package company
    :ensure t
    :hook (after-init . global-company-mode)
    :custom
    (company-idle-delay 0.2))
</example>

</pattern> </lsp_integration>

<modern_packages> <tool name="vertico"> <description>Vertical completion UI with orderless, marginalia, and consult</description> <example> (use-package vertico :ensure t :init (vertico-mode))

code

  (use-package orderless
    :ensure t
    :custom
    (completion-styles '(orderless basic)))

  (use-package marginalia
    :ensure t
    :init (marginalia-mode))

  (use-package consult
    :ensure t
    :bind (("C-s" . consult-line)
           ("C-x b" . consult-buffer)
           ("M-g g" . consult-goto-line)))
</example>

</tool> <tool name="which_key"> <description>Display available keybindings</description> <example> (use-package which-key :ensure t :diminish :init (which-key-mode)) </example> </tool> <tool name="treesit"> <description>Tree-sitter integration (Emacs 29+)</description> <example> (setq treesit-language-source-alist '((python "https://github.com/tree-sitter/tree-sitter-python") (javascript "https://github.com/tree-sitter/tree-sitter-javascript") (typescript "https://github.com/tree-sitter/tree-sitter-typescript" "master" "typescript/src")))

code

  ;; Install grammars
  (mapc #'treesit-install-language-grammar
        (mapcar #'car treesit-language-source-alist))

  ;; Remap modes
  (setq major-mode-remap-alist
        '((python-mode . python-ts-mode)
          (javascript-mode . js-ts-mode)))
</example>

</tool> </modern_packages>

<context7_integration> <library name="Emacs Docs" id="/websites/emacsdocs" trust="7.5" snippets="6792" />

<usage_pattern> <step>Resolve library ID (known: /websites/emacsdocs)</step> <step>Fetch documentation with specific topic</step> <examples> <example topic="elisp">Emacs Lisp programming patterns</example> <example topic="use-package">Package configuration patterns</example> <example topic="org-mode">Org mode configuration</example> <example topic="magit">Magit usage and configuration</example> <example topic="hooks">Hook usage patterns</example> </examples> </usage_pattern>

<common_queries> <query topic="keybindings">Key binding patterns</query> <query topic="defun">Function definition</query> <query topic="advice">Advice system usage</query> <query topic="custom">Customization variables</query> </common_queries> </context7_integration>

<best_practices> <practice priority="critical">Enable lexical-binding in all Elisp files: -*- lexical-binding: t; -_-</practice> <practice priority="high">Use #'function-name for function references (enables byte-compiler warnings)</practice> <practice priority="high">Document functions with docstrings</practice> <practice priority="high">Namespace all symbols with package prefix</practice> <practice priority="medium">Prefer seq.el functions for sequence operations</practice> <practice priority="medium">Use pcase for complex pattern matching</practice> <practice priority="medium">Use defcustom for user-configurable options</practice> <practice priority="medium">Use provide at end of file</practice> <practice priority="medium">Prefer :custom over setq in use-package</practice> <practice priority="medium">Use :hook instead of add-hook in use-package</practice> <practice priority="medium">Lazy load packages with :defer, :commands, or :hook</practice> <practice priority="medium">Use native-compilation when available (Emacs 28+)</practice> <practice priority="medium">Prefer eglot for LSP (built-in, simpler)</practice> <practice priority="medium">Use tree-sitter modes when available (Emacs 29+)</practice> </best_practices>

<anti_patterns> <avoid name="dynamic_binding"> <description>Using dynamic binding when lexical is needed</description> <instead>Add lexical-binding: t to file header</instead> </avoid>

<avoid name="hardcoded_paths"> <description>Hardcoding absolute paths</description> <instead>Use expand-file-name, user-emacs-directory, or locate-user-emacs-file</instead> </avoid> <avoid name="require_at_top"> <description>Requiring packages at top level unconditionally</description> <instead>Use autoload, use-package with :defer, or eval-after-load</instead> </avoid> <avoid name="global_state"> <description>Modifying global state without restoration</description> <instead>Use let-binding or save-excursion/save-restriction</instead> </avoid> <avoid name="lambda_in_hooks"> <description>Adding lambdas to hooks (hard to remove)</description> <instead>Define named functions and add those</instead> </avoid> <avoid name="setq_for_custom"> <description>Using setq for defcustom variables</description> <instead>Use customize-set-variable or :custom in use-package</instead> </avoid> <avoid name="cl_library"> <description>Using deprecated cl library</description> <instead>Use cl-lib with cl- prefixed functions</instead> </avoid> <avoid name="eval_after_load_string"> <description>Using eval-after-load with string</description> <instead>Use with-eval-after-load or use-package :config</instead> </avoid> <avoid name="inhibit_startup"> <description>Complex logic in early-init.el</description> <instead>Keep early-init.el minimal (frame settings, package setup)</instead> </avoid> </anti_patterns> <workflow> <phase name="analyze"> <objective>Understand Emacs Lisp requirements</objective> <step>1. Check package dependencies and autoloads</step> <step>2. Review existing configuration patterns</step> <step>3. Identify hook and advice usage</step> </phase> <phase name="implement"> <objective>Write idiomatic Emacs Lisp code</objective> <step>1. Use lexical binding</step> <step>2. Follow Emacs Lisp conventions</step> <step>3. Provide appropriate customization options</step> </phase> <phase name="validate"> <objective>Verify Emacs Lisp correctness</objective> <step>1. Byte-compile without warnings</step> <step>2. Test in clean Emacs instance</step> <step>3. Verify keybindings don't conflict</step> </phase> </workflow>

<related_skills> <skill name="org-ecosystem">Org-mode document creation, GTD workflow, Babel, export patterns</skill> <skill name="serena-usage">Symbol operations for elisp code navigation</skill> <skill name="context7-usage">Emacs documentation lookup via /websites/emacsdocs</skill> <skill name="investigation-patterns">Debugging package conflicts and performance issues</skill> <skill name="technical-documentation">Creating package documentation and README files</skill> </related_skills>

<error_escalation> <level severity="low"> <example>Byte-compilation warning</example> <action>Fix warning, ensure clean compilation</action> </level> <level severity="medium"> <example>Configuration error on startup</example> <action>Debug with --debug-init, fix issue</action> </level> <level severity="high"> <example>Package conflict or version mismatch</example> <action>Stop, present resolution options to user</action> </level> <level severity="critical"> <example>Emacs becomes unusable</example> <action>Provide recovery steps, require user action</action> </level> </error_escalation>

<constraints> <must>Use lexical-binding: t in all files</must> <must>Provide customization via defcustom</must> <must>Follow Emacs Lisp naming conventions</must> <avoid>Dynamic binding without justification</avoid> <avoid>Overriding standard keybindings silently</avoid> <avoid>Blocking operations in hooks</avoid> </constraints>