Skip to content

docs(skills): add agent skills for simple_module_python - #62

Merged
antosubash merged 2 commits into
mainfrom
feature/busy-mirzakhani-624b8e
Apr 29, 2026
Merged

docs(skills): add agent skills for simple_module_python#62
antosubash merged 2 commits into
mainfrom
feature/busy-mirzakhani-624b8e

Conversation

@antosubash

Copy link
Copy Markdown
Owner

Summary

Adds six standalone agent skills under skills/ (Anthropic Agent Skills format) so AI agents — Claude Code, Cursor, Codex, Windsurf, OpenCode, etc. — working in any simple_module_python project get the framework's invariants and workflows loaded into context on demand.

Publishable to skills.sh via:

npx skills add antosubash/simple_module_python

What's in the directory

Skill Use when
simple-module-creating Scaffolding a new module — entry-point, ModuleMeta, post-scaffold steps
simple-module-conventions Writing/reviewing module code — SQLModel-everywhere, settings layout, framework→plugin direction, Zod-in-hooks, locale rules
simple-module-database SQLModel tables, per-module Base, mixins, get_db lifecycle, no-session.commit()-in-services
simple-module-migrations Alembic in the host, branch_labels on first revision, autogenerate covering installed modules
simple-module-inertia-pages Render-key → file mapping, shared props (auth.user principal_serializer requirement), SM003/SM004/SM018
simple-module-doctor Full SM001–SM018 reference table with fix per code

Design

  • Standalone-friendly. No skill references paths internal to this dev repo (modules/, docs/, scripts/, packages/ui/, make targets). They install cleanly into a host project scaffolded with sm create-host or a module package scaffolded with sm create-module.
  • Canonical CLI. Skills point at sm create-module, sm host gen-pages, and uv run alembic … directly rather than this repo's Makefile shortcuts.
  • Description hygiene. Frontmatter description fields are "use when…" trigger phrases only — no workflow summaries. Per writing-skills guidance, summarized descriptions cause agents to follow the description in lieu of reading the body.
  • Word counts. All six SKILL.md files are 559–673 words (vs. typical 1000+ on skills.sh), keeping context-window cost low when an agent loads multiple at once.

Verifying claims

Spot-checked against the codebase before landing:

  • app.state.<module_lower> (no _settings suffix) — confirmed in modules/users/, modules/file_storage/, modules/background_tasks/. The diagnostics check accepts either lowercase package name or meta.name.lower().
  • sm host gen-pages — confirmed as the canonical CLI form (plugin subcommand under the host group).
  • ModuleMeta fields, mixin behavior, render-key mapping, branch-label requirement — verified against framework/core/, framework/db/, framework/hosting/.
  • Diagnostic codes SM001, SM003, SM004, SM007–SM018 exist; SM002, SM005, SM006 are reserved/retired (called out in the doctor skill).

Publishing

After merge, the skills are reachable at github.com/antosubash/simple_module_python/tree/main/skills and discoverable via npx skills add antosubash/simple_module_python. To seed the leaderboard telemetry, run that command once locally.

Test plan

  • Manually install in a clean directory: npx skills add antosubash/simple_module_python --list lists all six.
  • Install one skill into Claude Code: npx skills add antosubash/simple_module_python --skill simple-module-creating -a claude-code — verify .claude/skills/simple-module-creating/SKILL.md appears.
  • Skim each SKILL.md — confirm no make/scripts//modules/products//docs/ references to repo-internal paths.
  • Confirm npx skills add antosubash/simple_module_python --skill '*' -a claude-code installs all six.

Add six standalone agent skills under skills/ (Anthropic Agent Skills
format) so AI agents working in any simple_module_python project — host
or module package — get the framework's invariants and workflows
loaded into context on demand. Publishable to skills.sh via
`npx skills add antosubash/simple_module_python`.

Skills:
- simple-module-creating — scaffolding, entry-point, ModuleMeta
- simple-module-conventions — SQLModel-everywhere, settings layout,
  framework→plugin direction, Zod-in-hooks, etc.
- simple-module-database — per-module Base, mixins, get_db lifecycle
- simple-module-migrations — host-owned migrations, branch_labels
- simple-module-inertia-pages — render keys, shared props, SM003/4/18
- simple-module-doctor — full SM001–SM018 reference

The skills don't reference paths internal to this dev repo (modules/,
docs/, scripts/, packages/ui/, make targets), so they install
cleanly into user-land projects and reflect the canonical `sm` CLI
(create-module, host gen-pages) rather than this repo's Makefile.
Cover the full sm CLI surface: sm new (the wizard for greenfield
apps), sm create-host, sm create-module, sm host gen-pages, sm host
sync-js-deps, sm settings import-from-env, and sm users create-admin.
Includes preset/--with semantics (catalog keys for sm new, PascalCase
ModuleMeta names for sm create-host) and the per-flag option tables.
@antosubash
antosubash merged commit 136ae56 into main Apr 29, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant