Getting started / with an agent

Prompts that get the built-in version.

SmallStack is made to be extended by a coding agent — Claude Code, Codex, Cursor, Copilot, Gemini CLI. The repository carries AGENTS.md, installable skills and a skill file per subsystem. What the agent doesn't know is what you want, and whether you expect it to use what's already there. These prompts say so. Copy one, replace the parts in brackets, paste.

How a good SmallStack prompt is shaped

Every prompt below does five things. "Add a tickets page" gets a Django page that could have come from anywhere; this gets code that integrates.

Say what you are building and for whom — staff tool, end-user app, public site, API backend. The patterns differ, and the agent picks the wrong one if you don't say.
Name the skill files to read first. docs/skills/README.md is the index; AGENTS.md has the "if the user wants X, read Y" table. Naming them makes the first attempt the right one.
Ask for the built-in seams by name — a CRUDView with enable_api / enable_mcp, a @dataset, a @scheduled job, a status Monitor. An agent that doesn't know they exist will hand-roll a worse one.
State the gate. make lint and make test pass, and a new page is screenshotted on two palettes. Saying so stops "done" arriving early.
Say which repo it is. Upstream framework work must stay generic; a project built on SmallStack can be as specific as it likes.

Start a project

Build an application on SmallStack

A new app with models, pages, REST, MCP and search from one declaration each.

I'm building a help-desk tool for a small IT team on top of this SmallStack project. Before writing code, read AGENTS.md, then docs/skills/from-zero-to-running.md, docs/skills/django-apps.md, docs/skills/crud-views.md and docs/skills/modern-dark-theme.md.

Create a new app apps/tickets/ with these models: Ticket (title, requester, assignee, priority, status, due_at), Comment. Give each a CRUDView with list/detail/create/edit/delete pages, enable_api = True, enable_mcp = True and enable_search = True, so the same declaration gives me the admin pages, a REST API, MCP tools for Claude and keyword search. Register the app in the sidebar nav and add a dashboard widget on /smallstack/. Use the theme's CSS variables only — no hard-coded colours — and follow the page patterns in the skill files rather than inventing a layout.

Write tests under apps/tickets/tests/. Run make lint and make test until both pass, then screenshot the list page on the purple and orange palettes and show me. Don't commit; I'll review first.

Make the public site yours

The pages under apps/website/ become your product's marketing site, on the SmallStack theme.

I want the public site — the pages under apps/website/ — to become the marketing site for Acme Scheduling: home, features, pricing, contact. Read docs/skills/templates.md, docs/skills/navigation.md, docs/skills/modern-dark-theme.md and docs/skills/building-a-user-facing-site.md first. Keep the SmallStack theme and base template; change content, structure and the topbar navigation. Branding comes from the BRAND_* settings and static/brand/, not from edits to the theme. Every page must look right on all six palettes in both light and dark mode; screenshot each new page on two palettes before telling me it's done.

Build an end-user application

Signed-in customers, not staff — tenancy built in, not bolted on.

This is an app for our customers to track their own orders, not an admin tool. Read docs/skills/building-a-user-facing-site.md and docs/skills/mcp/end-user-tools.md before anything else — the tenancy rules there are the whole point. Use LoginRequiredMixin, scope every queryset by request.user in get_list_queryset, enforce writes with can_update/can_delete (the framework's check_object_permission enforces them on every write surface), and make the form scope its own foreign-key choices. Then build the CRUDViews for Order, Address with enable_api and enable_mcp, and prove in tests that one customer cannot read or write another's rows through the HTML pages, the REST routes or the MCP tools.

Add a capability

A model with pages, REST and MCP

The headline pipeline, in one class.

Add a Vendor model to apps/inventory/ with fields name, contact email, is_active, notes. Read docs/skills/crud-views.md and docs/skills/mcp/enable-mcp-for-a-model.md. One CRUDView class should give me the management pages, /smallstack/api/... REST routes and the MCP tools; add a migration, nav entry, tests, and run make lint and make test. Then run python manage.py api_doctor and python manage.py mcp_doctor and paste the results.

Put something on the calendar

A dataset with a date column becomes a calendar everywhere.

I want project milestones on the shared calendar at /smallstack/calendar/. Read docs/skills/calendar.md and docs/skills/datasets.md. If the dates live in a model column, declare a @calendar_dataset over it with start, title, status and the right access; if they're computed, write a @calendar_provider. Give the model's own list page a Table ⇄ Calendar ⇄ Board toggle with CalendarDisplay and RangeBoardDisplay. Add tests that the events appear in the right window and respect access.

Make something report-able

A dataset for dashboards, exports and agents — without more views.

Expose closed tickets as a @dataset so it can be filtered, charted and exported without more views. Read docs/skills/datasets.md. Declare the columns explicitly, mark the numeric ones that make sense as measures, add any ratio measure as a declared measures= entry (never an average of percentages), set enable_api=True, and check it in the staff browser at /smallstack/datasets/browse/.

Run something on a schedule

A task with a cadence, visible in the scheduler UI with a run history.

I need a nightly digest email to each team lead. Read docs/skills/scheduler.md and docs/skills/background-tasks.md. Write it as a @task and declare the cadence with @scheduled so it appears in the scheduler UI with a run history, rather than as a cron script. Make it idempotent and safe to run twice. Show me how to run it once by hand and how to watch it on /smallstack/scheduler/.

Gate an action behind a human decision

The approvals app: file, decide, react.

Before a refund over $500 goes through, a manager has to approve it. Read docs/skills/approvals.md and docs/skills/notifications.md. Register an @approval_kind, file the request with request_approval() from the place the action starts, react to the decision in the kind's callback, and make sure the approvers get a bell notification. The action must not happen on a rejected or expired request; write that test first.

Watch something on the status page

A Service and a cheap Monitor; the heartbeat does the rest.

Add our payment provider's API to /smallstack/status/. Read docs/skills/status-monitors.md. Register a Service and a Monitor whose check() is cheap, decide whether it is public, and show me the public status page with it on. Don't add a new monitoring loop; the heartbeat already runs the registered monitors.

Integrate with another system

Outbound webhooks on change; verified inbound receivers.

When an order is created, Slack / Zapier / our ERP needs to hear about it; and Stripe needs to be able to call us back. Read docs/skills/webhooks.md first — it covers both directions. Use enable_webhooks = True on the CRUDView for the outbound side and shape the payload with @webhook_transform; use @webhook_handler with @webhook_verifier for the inbound side. Don't write an HTTP client or a signature check by hand; the framework has them.

Build a page that fits the theme

Cards, stat tiles and variables — checked on three palettes.

Build a weekly review page for the support team under apps/support/. Before touching a template, read docs/skills/modern-dark-theme.md and docs/skills/dashboard-cards.md. Use .card, .page-header-bleed, {% stat_card %} and the theme's CSS variables; no hex colours, no [data-theme="dark"] overrides. When it renders, screenshot it on the purple, orange and high-contrast palettes and fix anything that goes brown or muddy before showing me.

Publish

A blog, a changelog, a newsletter

The built-in blog app with the right visibility, instead of new models.

Set up a company changelog / engineering blog with an email list. Read docs/skills/blog.md and docs/skills/rss.md. Use the built-in blog app — a blog with the right visibility, the newsletter with double opt-in — rather than new models, and show me the public URL, the feed URL and where authors write.

Operate a project

Deploy

Kamal to a single VPS, with the questions asked up front.

Deploy this project to a single VPS at example.com with Kamal. Read docs/skills/kamal-deployment.md and docs/skills/docker-deployment.md. Walk me through what you need from me (server, DNS, registry, secrets) before you change anything, then set it up, deploy, and confirm /health/ and /status/ answer.

Pull in a new SmallStack release

Read the release notes for your project before merging.

This project is built on SmallStack and I want to update to the latest upstream release. Read docs/skills/integration-workflow.md and docs/skills/downstream-release-migration.md, then the UPGRADING.md and CHANGELOG.md entries between our version and the new one. Tell me what is breaking for this project before merging, merge, run migrations, make lint and make test, and summarise what changed in behaviour.

Find out what's wrong

There is a doctor command for most of it.

Claude Desktop can't see the MCP tools / Swagger is empty / the API returns 403. Read docs/skills/cli-tools.md first — there is a diagnostic command for most of this (api_doctor, mcp_doctor, sc doctor all). Run the right one, read /smallstack/logs/ for the request, and explain the cause before proposing a fix.

The pattern holds.

If the prompt you need isn't here: say the goal, name the skill, ask for the seam, state the gate.

Back to Getting Started The same prompts in Help → The skill index →