creating-internal-agents
Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, buyer-side assistants).
- Installs
- 205
- Last 24h
- +15
- Trending rank
- #7009
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/medusajs/medusa-agent-skills --skill creating-internal-agents- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads creating-internal-agents automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Creating Agents in Medusa
This skill covers the full stack for adding an internal, admin-facing AI agent to a Medusa project. These agents are used by merchants and store operators through the Medusa admin dashboard — not by customers on a storefront. For customer-facing agents (e.g. a storefront chatbot), a different architecture is needed: public API routes, no MedusaExec, and storefront auth.
Constraints
- Internal use only — this architecture is for admin users (merchants, operators, support staff), not customers. Routes live under
src/api/admin/, the UI lives in the Medusa admin dashboard, and access is gated by admin authentication throughout. - Authentication is non-negotiable — MedusaExec runs arbitrary TypeScript with full database access. All agent routes must use
AuthenticatedMedusaRequestand live undersrc/api/admin/. An unauthenticated endpoint is a remote code execution vulnerability. - Use MedusaExec, not custom tools — for any data operation, the agent writes TypeScript and executes it via MedusaExec. Only build a custom tool for capabilities that cannot be expressed as executable TypeScript (e.g. calling an external API with a secret key).
- One shared module, multiple agents —
AgentSessionandAgentMessageare shared infrastructure. Useagent_typeto distinguish sessions per agent. Never create separate models per agent. - Pass
MedusaContainerviaexperimental_context— never import services directly in tool files; that causes circular dependencies. - Stream format is NDJSON —
Content-Type: application/x-ndjson, one JSON object per line followed by\n. - Run migrations after adding or changing models (
npx medusa db:generate agent && npx medusa db:migrate). - Tool descriptions live in config, not inline in
tool()— the config object overrides them at runtime.
CRITICAL: Load Reference Files When Needed
⚠️ The quick reference below is NOT sufficient for implementation. Load the relevant reference file before writing any code.
| Task | Load this file |
|---|---|
| Defining conversation models | reference/data-models.md |
| Setting up the module service | reference/service.md |
| Configuring tools, prompt, streamText | reference/agent-setup.md |
| Building the POST chat endpoint | reference/api-route.md |
| Implementing NDJSON streaming | reference/streaming.md |
| Building the admin chat UI | reference/admin-extension.md |
| Giving the agent code execution capability | reference/medusa-exec.md |
Minimum requirement: Load at least the reference file matching your current task before writing code.
Related Skills
Load these alongside this skill when relevant:
building-with-medusa— Medusa module patterns, workflows, data model conventions. Load when implementing the module service or custom backend logic.building-admin-dashboard-customizations— Admin UI component patterns, TanStack Query, route registration. Load when building or extending the admin chat UI.
Architecture Overview
src/modules/agent/
index.ts ← Module() export + AGENT_MODULE constant
service.ts ← MedusaService + Anthropic client + stream(messages, container, config)
models/
session.ts ← AgentSession (shared across all agents, filtered by agent_type)
message.ts ← AgentMessage
agents/index.ts ← streamText() orchestration
tools/
medusa-exec.ts ← MedusaExec tool (primary tool for all data operations)
todo-write.ts ← TodoWrite tool
config/
<agent-type>.ts ← per-agent system prompt + tool descriptions
src/api/admin/agent/<agent-type>/
route.ts ← POST (AuthenticatedMedusaRequest, session lifecycle, NDJSON stream)
sessions/route.ts ← GET session list (filtered by agent_type)
sessions/[id]/route.ts ← GET messages for a session
src/admin/routes/<agent-type>/
page.tsx ← React chat UI (admin extension)
src/lib/code-mode/
executor.ts ← sandboxed TypeScript executor used by MedusaExec
Common Mistakes
Verify you are NOT doing these:
Security:
- Agent route uses
MedusaRequestinstead ofAuthenticatedMedusaRequest - Agent route placed outside
src/api/admin/
Architecture:
- Creating separate
AgentSession/AgentMessagemodels per agent instead of usingagent_type - Importing services directly in tool files instead of resolving from
experimental_context - Building a custom tool for a data operation instead of using MedusaExec
Streaming:
- Missing
res.end()after the stream loop (response never closes) - Missing
Transfer-Encoding: chunkedorContent-Type: application/x-ndjsonheaders - Not buffering incomplete lines on the client (JSON parse errors on split packets)
Module:
- Forgetting to register the module in
medusa-config.ts - Forgetting to run migrations after changing models
- Hardcoding tool descriptions in
tool()instead of the config object
Reference Files Available
reference/data-models.md - model.define(), agent_type discriminator, relationships, migrations
reference/service.md - MedusaService extension, Anthropic init, stream(), module index, config registration
reference/agent-setup.md - streamText(), MedusaExec tool wiring, system prompt, context passing
reference/api-route.md - POST route, session lifecycle, message persistence, streaming headers
reference/streaming.md - NDJSON emission, fullStream iteration, chunk types, client-side parsing
reference/admin-extension.md - React chat UI, streaming fetch, message rendering, tool call display, session sidebar
reference/medusa-exec.md - Executor setup, MedusaExec tool, query.graph() patterns, error codes
Testing
Once the agent is implemented, test it end-to-end directly in the admin dashboard:
- Start the Medusa dev server (
npx medusa develop) - Open the admin dashboard and navigate to the agent's page in the sidebar (the label set in
defineRouteConfig) - Type a simple read-only prompt — e.g. "How many products are in the store?" — and submit
- Verify the response streams in and a new session appears in the sidebar
- Send a follow-up message in the same session to confirm conversation history is preserved
- Reload the page, select the session from the sidebar, and confirm the message history is restored from the database
If anything is broken, check:
- Browser network tab — the POST request should return
Content-Type: application/x-ndjsonwith chunked lines - Server logs —
[agent] tool_calland[agent] step_finishlines confirm the agent is running - Database —
agent_sessionandagent_messagetables should have rows with the correctagent_type
FAQ
What does the creating-internal-agents skill do?
Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, buyer-side assistants).
How do I install creating-internal-agents?
Run npx skills add https://github.com/medusajs/medusa-agent-skills --skill creating-internal-agents in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/creating-internal-agents/ (personal) or .claude/skills/creating-internal-agents/ (project).
Which AI agents can use creating-internal-agents?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is creating-internal-agents safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains creating-internal-agents?
It is published by medusajs in medusajs/medusa-agent-skills. It has 205 recorded installs.
More from medusajs/medusa-agent-skills
storefront-best-practices
medusajs/medusa-agent-skills
ALWAYS use this skill when working on ecommerce storefronts, online stores, shopping sites. Use for ANY storefront component including checkout pages, cart, payment flows, product pages, product listings, navigation, homepage, or ANY page/component in a storefront. CRITICAL for adding checkout, implementing cart, integrating Medusa backend, making a store agent-friendly for AI shopping agents, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, backend integration guidance.
building-with-medusa
medusajs/medusa-agent-skills
Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.
building-admin-dashboard-customizations
medusajs/medusa-agent-skills
Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.
building-storefronts
medusajs/medusa-agent-skills
Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.
db-migrate
medusajs/medusa-agent-skills
Run database migrations in Medusa
db-generate
medusajs/medusa-agent-skills
Generate database migrations for a Medusa module
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available