new-emacs-package
Create a new standalone Emacs package of Pablo's from scratch, or turn existing code into one, through to a public, documented and registered package. Use for "create a new package", "make this a prop
SKILL.mdclaude/skills/new-emacs-package/SKILL.md
GitHubNew Emacs package
This skill sequences the work. Each step's procedure belongs to the skill named in it: load that skill at the step and follow it rather than improvising. Do not copy their rules here.
Decisions to collect first
Before writing files, put every decision the whole task needs in one list
(global instructions, "Ask for decisions once per task"): the name, public or
private repository, creating and pushing the GitHub repository, the config.org
recipe and tangle, the GitHub profile card (add-to-emacs-packages treats it as
separately authorized) and any live test that writes to an outside service.
Submitting to MELPA or another archive is not part of this workflow unless Pablo
asks.
Steps
- Name. Choose a name that says what the package does, then check it is
free: no MELPA recipe (
https://raw.githubusercontent.com/melpa/melpa/master/recipes/NAMEreturns 404) and no Emacs package of that name on GitHub. - Source location. Ask the running Emacs for
elpaca-sources-directory(never guess the profile) and create the package atSOURCES/NAME/, withgit initand the remotehttps://github.com/benthamite/NAME.git. That directory becomes the canonical checkout once the recipe in step 7 exists (dotfiles-context). Keep scratch work out of the Drive tree. - Layout. Match Pablo's published packages (for example
annas-archive,elfeed-ai,mullvad):NAME.el, from the yasnippetemacs/yasnippets/emacs-lisp-mode/package-header, withPackage-Requires,KeywordsandURL: https://github.com/benthamite/NAME; split large packages intoNAME-*.ellibraries;COPYING.txt(GPL-3.0), copied from a sibling package;test/NAME-test.eland an executabletest/run-tests.sh, so the commit guard has a tracked check (copyforethought.el's orelfeed-ai's and adapt);README.org(step 5),README.md(step 5) and the exportedNAME.texi.
- Code and tests. Follow
elisp-conventionsthroughout: never block the main thread on the network, test with the batch runners, commit with evidence. For code that writes to an outside service, give the tests a fake of that service; run live writes only against a sandbox account Pablo approved. Before calling the code done, have an independent reviewer audit it (code-audit, or a subagent given the code rather than your conclusions). - Documentation.
document-elisp-packagewrites theREADME.orgmanual and its Texinfo export; thengenerate-readmederivesREADME.md. - Publish. With Pablo's approval, create the public repository
(
gh repo create benthamite/NAME --public --source . --push). - Install. Add a
config.orgsection in the matching part of the file: a heading with an:ID:, a one-line description linking the repository, and(use-package NAME :ensure (:host github :repo "benthamite/NAME") ...)(see theelfeed-aisection). Followdotfiles-contextfor editing and tanglingconfig.org, and verify the package in the live session withelisp-live-verify. - Register. Run
add-to-emacs-packages: the entry inmy-emacs-packages.org(the website list), its documentation note, the repository's About fields and, if authorized, the card on the GitHub profile. - Release. Tag a first version only when Pablo asks, with
release-package.
Done when
The repository is public and pushed, the package loads in the live Emacs from
its Elpaca recipe, its tests pass, README.org, README.md and the Texinfo
manual agree with the code, and it appears on the website list (and, if
authorized, the profile). Report anything left undone as open, not done.