luthersystems/elps / .claude/skills/add-stdlib-package
add-stdlib-package
Verified/add-stdlib-package — New Standard Library Package Skill
Creates a new stdlib package for the ELPS interpreter. Follows the established pattern from existing packages like libmath.
Trigger
Use when asked to add a new standard library package (e.g., file I/O, crypto, HTTP client, etc.).
Workflow
1. Plan the Package
Before writing code, define:
- Package name (lowercase, e.g.,
"file","crypto") - Functions to export with their signatures
- Any global constants to expose
- Package-level documentation
2. Create the Package Directory
Create lisp/lisplib/lib<name>/lib<name>.go:
package lib<name>
import (
"github.com/luthersystems/elps/lisp"
"github.com/luthersystems/elps/lisp/lisplib/internal/libutil"
)
// DefaultPackageName is the package name used by LoadPackage.
const DefaultPackageName = "<name>"
// LoadPackage adds the <name> package to env.
func LoadPackage(env *lisp.LEnv) *lisp.LVal {
prevPkg := env.Runtime.Package.Name
defer env.InPackage(lisp.Symbol(prevPkg))
name := lisp.Symbol(DefaultPackageName)
e := env.DefinePackage(name)
if !e.IsNil() {
return e
}
e = env.InPackage(name)
if !e.IsNil() {
return e
}
env.SetPackageDoc(`One-line description of the package.
Detailed description of what the package provides.`)
// Optional: global constants
// env.PutGlobal(lisp.Symbol("my-const"), lisp.Int(42))
// env.SetSymbolDoc("my-const", "Description of the constant.")
// env.Runtime.Package.Exports("my-const")
for _, fn := range builtins {
env.AddBuiltins(true, fn)
}
return lisp.Nil()
}
//elpsvet:allow package builtin table; formals are sealed by libutil at construction and shared via registrationFormals (lisp.LEnv.AddBuiltins)
var builtins = []*libutil.Builtin{
libutil.FunctionDoc("my-func",
lisp.Formals("arg1", "arg2"),
builtinMyFunc,
`Description of what my-func does.
Returns the result of ...`),
}
func builtinMyFunc(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal {
arg1 := args.Cells[0]
arg2 := args.Cells[1]
// Implementation
_ = arg1
_ = arg2
return lisp.Nil()
}
Key Rules
- Always use
libutil.FunctionDoc()— neverlibutil.Function(). All functions must have docstrings. CI enforces this viaelps doc -m. - Use
lisp.Formals()for argument declarations. Modifiers are plain symbols:- Required:
lisp.Formals("arg1", "arg2") - Optional:
lisp.Formals("required", lisp.OptArgSymbol, "opt-arg")(&optional) - Variadic:
lisp.Formals("required", lisp.VarArgSymbol, "rest-args")(&rest) - Keyword:
lisp.Formals("required", lisp.KeyArgSymbol, "key-arg")(&key)
- Required:
- Error propagation: Return
env.Errorf("message: %v", detail)for errors — never use Go'serrorinterface - Exports:
env.AddBuiltins(true, fn)exports each function. Globals need an explicitenv.Runtime.Package.Exports("name", ...) - The
//elpsvet:allowon thebuiltinstable is required:make elpsvetflags any package-level var that keeps*lisp.LValreachable. Keep the justification; see/elpsvet - Native Go values returned to lisp must be publishable by templates — a scalar or a struct value embedding
internal/templatepolicy.Marker(seelibtime,libregexp).make elpsvetreports anything else; see/elpsvet - Allocation limits: size-dependent results must check
env.Runtime.CheckAlloc/MaxAllocBytes()before allocating (seelibbase64) - Step charges: a builtin whose work grows with input or output size charges
libutil.ChargeKiB(env, n)for the bytes it scans or builds and returns its error as is, so an enforced step budget bounds it (seelibstring,libjson)
3. Register in the stdlib loader
lisplib.LoadLibrary() and LoadRuntimeLibrary() both delegate to
stdlib.Load in internal/stdlib/stdlib.go. Edit that file:
- Add import:
"github.com/luthersystems/elps/lisp/lisplib/lib<name>" - Add to the loader sequence in
Load(), before the finalInPackage(only inside theif testingblock if the package holds mutable per-VM state, likelibtesting):
e = lib<name>.LoadPackage(env)
if !e.IsNil() {
return e
}
4. Write Tests
Create lisp/lisplib/lib<name>/lib<name>_test.go (the _test package suffix avoids an import cycle):
package lib<name>_test
import (
"testing"
"github.com/luthersystems/elps/elpstest"
)
func TestPackage(t *testing.T) {
r := &elpstest.Runner{}
defer r.Close()
r.RunTestFile(t, "lib<name>_test.lisp")
}
Create the lisp test beside it at lisp/lisplib/lib<name>/lib<name>_test.lisp:
(use-package 'testing)
(use-package '<name>)
(test "my-func basic usage"
(assert-equal (my-func "arg1" "arg2") expected-result))
(test "my-func edge case"
(assert-nil (my-func "" "")))
(test "my-func error handling"
;; testing has no assert-error: catch the condition and check it was raised
(assert (handler-bind ([condition (lambda (c &rest _) true)])
(my-func)
false))) ; missing args
5. Verify
go test ./lisp/lisplib/lib<name>/... # Package tests pass
make test # Full suite passes
./elps doc -m # No missing docstrings
./elps doc <name> # Package docs render correctly
Checklist
- Package directory created at
lisp/lisplib/lib<name>/ -
LoadPackage()follows DefinePackage → InPackage → SetPackageDoc → AddBuiltins pattern - All functions use
libutil.FunctionDoc()(notFunction()) - All public symbols exported via
Exports() - Package registered in
internal/stdlib/stdlib.goLoad() -
builtinstable carries its//elpsvet:allowjustification;make elpsvetclean - Package listed in the
lisp/lisplib/bullet ofAGENTS.md - Tests written with
elpstest.Runner+.lisptest file -
elps doc -mpasses (no missing docstrings) -
make testpasses -
docs/lang.mdupdated if package is user-facing
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |