creating-internal-agents — Claude Code skill: Medusa admin AI agents
creating-internal-agents — a skill for building an admin-side AI agent in Medusa: conversation models, module service, streamText() runtime, NDJSON route and a chat page.
no license 500 installs ★ 237 updated 2026-10-21
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a claude-codeWhat creating-internal-agents does
The skill walks through the whole stack of an admin-side AI agent in Medusa: conversation models, a module service that holds the Anthropic client and a stream() method, the runtime built on streamText(), a POST route streaming NDJSON, and a chat page inside the dashboard.
Data work goes through MedusaExec, where the agent writes TypeScript and runs it. A custom tool earns its place only when code can't do the job, an outside API behind a secret key for instance. Every agent shares AgentSession and AgentMessage; the agent_type field keeps their sessions apart. Pass the container through experimental_context — importing services straight into tool files creates circular dependencies.
Admin auth is not optional. Routes sit under src/api/admin/ and take AuthenticatedMedusaRequest, since MedusaExec executes arbitrary code with database access. An endpoint left open there means remote code execution. Model changes need migrations (npx medusa db:generate agent && npx medusa db:migrate), and the skill wants the matching reference file loaded before any code gets written.
What it helps with
- define conversation models for an admin chat agent in Medusa
- set up a module service with the Anthropic client and
stream() - stream an agent reply as NDJSON from a POST route
- add a chat page to the Medusa admin dashboard
- let the agent execute TypeScript through MedusaExec
Example prompts for the agent
- Set up the
agentmodule withAgentSessionandAgentMessageplus anagent_typefield - Create the POST route under
src/api/admin/agent/withAuthenticatedMedusaRequestand NDJSON streaming - Add an admin chat page for a store operations agent
How to install creating-internal-agents
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a claude-code2Manually: put the files in place
~/.claude/skills/creating-internal-agents/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/creating-internal-agents/
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a codex2Manually: put the files in place
.agents/skills/creating-internal-agents/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a cursor2Manually: put the files in place
.cursor/skills/creating-internal-agents/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install medusajs/medusa-agent-skills plugins/medusa-dev/skills/creating-internal-agents2Manually: put the files in place
.github/skills/creating-internal-agents/SKILL.md1Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a gemini-cli2Platform CLI
gemini skills install https://github.com/medusajs/medusa-agent-skills --path plugins/medusa-dev/skills/creating-internal-agentsManually: put the files in place
.devin/skills/creating-internal-agents/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about creating-internal-agents
How do I install creating-internal-agents in Claude Code?
Run npx skills add medusajs/medusa-agent-skills --skill creating-internal-agents -a claude-code. The skill file lands at ~/.claude/skills/creating-internal-agents/SKILL.md.
What does creating-internal-agents do?
It covers each layer of an internal Medusa agent: data models, the module service, tools and system prompt, NDJSON streaming, and the admin UI. Before code, it asks you to load the reference file for the task at hand.
Does it work for a storefront chatbot?
No. It targets agents run by merchants and operators behind admin authentication. Customer-facing bots need a different setup: public routes, storefront auth, no MedusaExec.