smarter-extension-cookiecutter v1.0 Release: A New Smarter Extension in One Command

The Smarter Project now publishes an official Cookiecutter template for Smarter Extensions, smarter-extension-cookiecutter. One command asks you a few questions and generates a complete extension repository, with a working tool, its tests, and the same lint, test and release setup as the official extensions.

pip install cookiecutter
cookiecutter gh:smarter-sh/smarter-extension-cookiecutter

A Smarter Extension is a Python package that adds tools to the LLMs of every Smarter platform that installs it. Until today, starting one meant copying an official extension, such as weather, by hand, and stripping out everything that was about the weather. That works, but it’s slow, and it’s easy to leave a stray name or setting behind. The template does that job for you, correctly, every time.

Sixteen questions, then a repository

Cookiecutter asks one question at a time, and most answers have a default worked out from the ones before. Name your extension “Reading Time”, and the template suggests the slug reading-time, the Python package reading_time, the repository smarter-extension-reading-time and the tool class ReadingTime. Press Enter to accept each one.

• The name and the slug. The name is what administrators see. The slug is the permanent identifier that LLMClients list in their manifests.
• The starter. web-api gives you a tool that calls an HTTP API, with a secret api_key setting, an api_url setting, and a separate module for the API calls, mocked in its tests. pure-function gives you a tool that computes its result in Python and needs no settings.
• The tool. Its name (the LLM sees it as ext_<slug>_<name>), how long to cache its results, and how long a call may run.
• You. Your name, email, GitHub account and publisher id in the registry.
• The license. AGPL-3.0 (Smarter’s own), MIT or Apache-2.0. The extensions you generate are yours to license as you choose.

Before it writes a single file, the template checks the answers with the same rules that Smarter applies when it loads an extension. A slug with capital letters, a tool name that starts with a digit or a timeout of 600 seconds stops generation right there, with a message that names the question and how to fix it. You find out in the first minute, not when an administrator tries to install your release.

To generate from a particular release of the template, add --checkout v1.0.0.

What you get

smarter-extension-<slug>/
├── pyproject.toml            [project] and [tool.smarter]: slug, tools, settings
├── <package>/
│   ├── __init__.py           the documentation administrators read
│   ├── tools.py              the tool, a SmarterExtensionTool subclass
│   ├── models.py             its arguments and result (web-api)
│   └── services.py           the calls to the third-party API (web-api)
├── tests/                    unittest tests, services mocked, 100% coverage
├── scripts/                  the test runner, and the release scripts
├── .github/workflows/        test, lint and release
├── release.config.js         semantic-release
├── .pre-commit-config.yaml   Smarter's lint standard, and commitlint
├── Makefile                  init, test, validate, lint, package
├── CLAUDE.md, skills/        instructions for AI coding agents
└── README, LICENSE, SECURITY, CONTRIBUTING, CHANGELOG, issue and pull request templates

• A tool that works. Both starters are real tools, not placeholders. The tests of the web-api starter (9 of them) and the pure-function starter (6) pass at 100% coverage, and Smarter’s own validate_extension command accepts both.
• Tests that run against Smarter. An extension runs inside a Smarter platform, so make test runs its tests in the smarter-app container of a local Smarter development environment, against Smarter’s own code. make validate then runs the checks that the installer and the registry make.
• The house style. black, flake8, isort, autoflake, bandit, codespell, pyupgrade, pydocstringformatter and Prettier run on every commit, and commitlint checks each commit message. Every module, class and function in the starters has a Sphinx docstring, so your extension starts out documented to the standard it will be held to.
• Releases without a checklist. On each push to main, semantic-release reads your conventional commits, picks the next version, updates the changelog, tags the commit, and attaches the extension’s archive and its sha256 to a GitHub release. The release workflow’s summary prints the two lines that your registry pull request needs.
• Shared with the official extensions. The release scripts, the test and release workflows, the test runner and the agent skills are the same files, byte for byte, that the weather, calculator and date-calculator extensions use. A fix to one of them is made in the template and in every official extension.
• Ready for a coding agent. The generated CLAUDE.md and four skills (development, testing, git commits and releases) tell an agent such as Claude Code what an extension may import, how to test it and how its releases work. .claude/skills is linked to skills/, so other agents find the same instructions.

📖 Smarter Extension developer guide

Built like a dependency

The template is tested like any other Smarter package. Its own suite of 22 tests generates extensions with many different answers and checks what comes out, including a test that holds both starters, and the template’s own tests, to the docstring standard. A second target, make test-generated, generates both starters and runs their own tests in a Smarter container. CI runs the tests on every pull request, and semantic-release makes each release of the template from its commits, exactly as it does for the extensions it generates.

Try it

• Build something. Run the two commands at the top of this post, pick a starter, and replace the starter’s tool with yours. The step-by-step tutorial, How to Build a Smarter Extension in Python With Cookiecutter, walks through it from installing Cookiecutter to installing your extension, and assumes only a little Python.
• Publish it. When your extension is ready, open a pull request on the Smarter Extension registry, and every Smarter platform can install it from its Extensions page.
• Ask for what’s missing. Open an issue on the template’s repository for a starter you’d like, or an answer it refused that it shouldn’t have.

The changelog is on GitHub, with the v1.0.0 release. The source is at github.com/smarter-sh/smarter-extension-cookiecutter, the extension docs are at docs.smarter.sh, and Smarter itself is at github.com/smarter-sh/smarter.