---

name: emacs-literate-programming description: Use when modifying Emacs config files - ensures you edit .org source files not generated .el files, and properly tangle changes

Emacs Literate Programming Workflow

Overview

Literate Configuration: Jeff's Emacs config uses org-mode files as source. Editing .el files directly is forbidden - they're auto-generated and changes will be overwritten.

Core principle: .org files are source of truth → tangle to .el files → Emacs loads .el files

When to Use

Use this skill when:

• About to edit any file in emacs/ directory
• User mentions Emacs configuration changes
• You see both .org and .el files in emacs/ directories
• Auto-tangle fails or syntax errors appear

DO NOT edit .el files directly - they get overwritten when tangled

Quick Reference

Tangling Methods

Auto-Tangle (Primary Method)

• Trigger: Save the .org file
• Requirement: #+auto_tangle: y header in file
• Result: Automatically generates .el file

Manual Tangle in Emacs

• When: Auto-tangle fails or disabled
• Command: C-c C-v t (org-babel-tangle)

CLI Tangling (bin/tangle-org.sh)

Copy# Single file
./bin/tangle-org.sh emacs/major-modes/org.org

# All org files
find emacs/ -name "*.org" -exec ./bin/tangle-org.sh {} \;

Features: Auto-finds Emacs, validates files, batch mode, clear errors

Required File Headers

Copy#+title: Module Name
#+property: header-args:emacs-lisp :tangle module-name.el
#+auto_tangle: y

After Tangling

1. Restart Emacs or use jf/reload-module to load changes
2. Test changes ensure they work
3. Commit both files - keep .org and .el in sync

Common Mistakes

Troubleshooting

When auto-tangling or manual tangling fails, see troubleshooting-tangling.md for:

• Systematic debugging process
• Common issues and solutions (especially property activation with C-c C-c)
• Understanding multiple tangle directives and precedence
• Path resolution (relative vs absolute)
• Header arguments syntax reference

Quick fix for most issues: Press C-c C-c on the #+PROPERTY: header-args line to activate it.

Syntax Protection

Claude Code hook (validate_elisp_syntax.py) validates elisp before writing .el files to prevent invalid code.