create-agent
Skill18 starsChanged 3 months agoMITView on GitHub
Create a new ginnie-agents agent end-to-end — generates files from the template, walks the user through Slack app creation, sets up credentials, registers in the team directory, and restarts the listener. Use when the user says "create agent", "new agent", "add agent", or names an agent role to build (e.g. "build me a sales agent").
- Reads credentials
- Installs packages
- Sends data out
38 other projects use a version of this.
Adopted by
Most recently taken up by
- microsoft/AgentHosting.Clitheir own version, first seen Nov 15, 2026
- lalulali/vespyrtheir own version, first seen Nov 6, 2026
- cognitedata/builder-skillstheir own version, first seen Nov 4, 2026
- harness/harness-skillstheir own version, first seen Nov 1, 2026
- fxmartin/claude-code-configtheir own version, first seen Oct 31, 2026
- agno-agi/agentos-dockertheir own version, first seen Oct 30, 2026
Used with
Projects with it also use deploy-platform, setup-platform and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
agno-agiSkilldeploy-platform
Deploy this AgentOS using its own provider instructions, configure JWT verification, and verify the public service. Use for first deployment, redeployment, or production configuration changes.
Also in 5 projects that use this
agno-agiSkillsetup-platform
Set up this AgentOS from a fresh clone — confirm Docker, configure .env, boot the containers, prove the MCP endpoint live, connect the AgentOS UI, then build the user's first agent. Use when the user asks to set up the platform, get started, or bring this repo up on a new machine.
Also in 5 projects that use this
ElasticSkillcreate-integration
Use when creating a new Elastic integration package, scaffolding data streams, answering package layout or structure questions, or running the end-to-end integration build workflow. Covers package topology, scaffold commands, post-scaffold edits, and full orchestration of CEL/pipeline/test subagents.
Also in 3 projects that use this
MicrosoftSkillcreate-hook
Create a hook (.json) to enforce policy or automate agent lifecycle events.
Also in 5 projects that use this
AnasX7Skillimprove
Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.
Also in 5 projects that use this
ElasticSkillcreate-skill
Interactively create a new Claude Code skill and add it to the elastic-docs-skills catalog. Use when the user wants to generate a new skill, scaffold a slash command, or build automation for docs tasks.
Also in 13 projects that use this
- +3 more from agno-agi
Other versions38 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 38
- microsoft/vscode★ 195ksame name
- gnekt/My-Brain-Is-Full-Crew★ 3.9ksame name
- EvolutionAPI/evo-nexus★ 545same name
- evolution-foundation/evo-nexus★ 535same name
- openma-ai/open-managed-agents★ 360same name
- luanmorenommaciel/agentspec★ 256same name
- harness/harness-skills★ 134same name
- microsoft/copilot-studio-plugin★ 82same name
- Azure-Samples/art-voice-agent-accelerator★ 74same name
- TOKTOKHAN-DEV/agent-company★ 74same name
28 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- doctorSkill
- logsSkill
- manage-known-usersSkill
- manage-routinesSkill
- manage-work-hoursSkill
- setupSkill
- setup-watcherSkill
- update-frameworkSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. 0 are common, 5 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 35 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Don't shortcut. The agent's quality follows from how carefully you elicit role, voice, schedule, and boundaries.
- Distinctive: line 35
After drafting, show the full SOUL.md to the user before writing.
- Very specific: line 52
If the user has a preferred image-creation skill installed (e.g., media-pipeline), suggest they invoke it with the derived prompt — but …
- Very specific: line 70
Start from templates/agent/PROMPT.md.
- Distinctive: line 82
Ask: does this agent have a routine?
- Very specific: line 88
Use the manage-routines skill format.
- Very specific: line 106
If SLACK_CONFIG_TOKEN and SLACK_CONFIG_REFRESH_TOKEN are both set → programmatic path (6A).
- Very specific: line 212
After install, OAuth & Permissions → copy the Bot User OAuth Token (xoxb-…).
- Very specific: line 222
Should return ok: true with user_id and bot_id.
- Very specific: line 257
Use the manage-known-users skill flow:
- Very specific: line 258
Should this agent be visible to (a) all agents, (b) specific agents, or (c) no agents?
- Very specific: line 259
Write to the right known-users.json file(s) with:
- Very specific: line 293
Check the listener log for the matching [@mention] and [<agent>] Container done lines.
- Distinctive: line 295
If no response in 60 seconds:
- Very specific: line 296
Check pm2 logs ginnie-agents-listener for errors.
- Very specific: line 297
Verify the bot is /invited to the channel.
- Very specific: line 298
Verify Socket Mode is enabled and xapp- token has connections:write.
- Very specific: line 299
Verify auth.test still returns ok: true.
- Distinctive: line 310
Don't claim "done" until smoke test passes.
“Common” is measured: kept by at least 6 in 10 of the 35 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Create an Agent
A full agent is: PROMPT.md (mission), SOUL.md (voice), config.json (operational), credentials.json (Slack + role-specific keys), slack.json (Slack metadata), schedules.json (routines), memory/ (rules, playbook, episodes), known-users.json (optional, per-agent), skills/ (optional, per-agent).
Don't shortcut. The agent's quality follows from how carefully you elicit role, voice, schedule, and boundaries.
Step 1 — Discovery
Ask:
- Name — what's the agent called? Pick a single short word, ideally a human-sounding name, not a function name. ("Maya", not "sales-bot".) The Slack bot will display this name.
- Role / mission — one sentence: what does this agent own? E.g. "monitor the customer fleet and open tasks when machines go down."
- Channel — which Slack channel will they live in?
#sales,#operations, etc. Will the user create a new channel or use an existing one?
Suggest a slug for the agent's directory name: lowercase the name, no spaces. Example: Maya → agents/maya/. Confirm with the user.
Step 2 — Voice (SOUL.md)
This is the most important step. Personality lives in SOUL.md, not PROMPT.md. Don't skip it. A flat-affect agent is a worse agent.
Walk the user through these four sections (one at a time, draft as you go):
- Origin — where they're from, age, family/partner status, the one career moment that shaped them, why they're on this team. 3–5 sentences. Concrete, not philosophical. Example: "Maya is 31, grew up in Lisbon, moved to London at 24 for a B2B SaaS sales role. Got promoted to head of mid-market by 28, then got laid off in '24. Joined as the team's first sales analyst because she missed structure."
- Life outside work — hobbies, weekends, recurring rituals. 3–5 sentences. Pick things that sound like a real person's calendar.
- Voice — sentence shape, language defaults, gender form (in gendered languages), emoji rules, banned words. Concrete: "short sentences, dry, never uses 'just' or 'super'."
- Quirks — 2–3 specific tics. The smaller and weirder, the better. "Maya always closes a long thread with a one-line summary. Refuses to use the rocket emoji. Uses 'cool' as a full sentence."
After drafting, show the full SOUL.md to the user before writing. Get explicit approval. Edit on feedback. SOUL is what makes the agent feel like a person; do not rush this.
Step 2.5 — Avatar (image)
A real Slack avatar makes the agent feel like a person, not a bot. Don't skip this. Slack will use this image everywhere the agent shows up (DMs, @mentions, channel messages, sidebar list).
The framework is image-tool-agnostic. The user picks whichever image AI they prefer — Midjourney, ChatGPT/DALL-E, Gemini, Stable Diffusion, Flux, Adobe Firefly, etc. Your job is to derive a strong prompt from the SOUL.md you just approved and walk them through producing the image.
Derive a prompt from SOUL. The exact wording depends on the agent, but the shape is: subject description (age, gender presentation, vibe), framing (square crop, headshot, centered subject because Slack auto-crops to a circle), style notes (photographic vs. illustrative, lighting), and constraints (no text, no logo, no watermark). Pull concrete details from SOUL.md so the picture matches the personality, e.g.:
"Portrait of a calm 30-something gender-neutral person, slight wry expression, natural late-morning light, photographic, square crop, headshot framing, soft neutral background, no text, no logo. Subject looks like someone who walks before coffee and plays bad chess on weekends."
Show the user:
- The derived prompt (let them edit it).
- Required spec: square 1024×1024 PNG. Slack auto-crops to a circle, so the subject should be centered.
- Tell them to run it through their image AI of choice (Midjourney, DALL-E, Gemini, Flux, …). The output is rarely already square.
If the user has a preferred image-creation skill installed (e.g., media-pipeline), suggest they invoke it with the derived prompt — but don't assume it exists.
Resize + square-crop with ImageMagick (works on any non-square input):
# Requires: brew install imagemagick (macOS) or apt-get install imagemagick (Linux)
magick "/path/to/your-image.png" -resize 1024x1024^ -gravity center -extent 1024x1024 "agents/<slug>/avatar.png"Verify:
test -f "agents/<slug>/avatar.png" && magick identify "agents/<slug>/avatar.png"You'll upload agents/<slug>/avatar.png to the Slack app's icon in Step 6 (manual drag-and-drop — Slack doesn't expose a bot-icon-set API).
Step 3 — Mission (PROMPT.md)
Start from templates/agent/PROMPT.md. Substitute:
{{AGENT_NAME}}→ agent name{{ROLE_DESCRIPTION}}→ from Step 1{{CHANNEL_NAME}}→ from Step 1{{CHANNEL_ID}}→ set toTBD; you'll fill it in Step 6 after creating the Slack app.{{ROLE_SPECIFIC_SECTION_TITLE}}and{{ROLE_SPECIFIC_INSTRUCTIONS}}— ask the user. What are this agent's specific responsibilities? What APIs do they touch? What does success look like? Be concrete; one section per major responsibility.{{ADDITIONAL_STARTUP_STEPS}}— what should the agent do at session start beyond reading credentials? E.g. "supabase link --project-ref X", "fetch latest fleet status from API Y."
Show the full PROMPT.md draft to the user. Iterate.
Step 4 — Schedule (schedules.json)
Ask: does this agent have a routine? Common patterns:
- "Daily report at 9am" →
0 9 * * * - "Hourly fleet scan during work hours" →
0 9-18 * * 1-5 - "Weekly summary on Mondays" →
0 8 * * 1 - "On-demand only" → leave
schedules.jsonempty ({"schedules": []})
Use the manage-routines skill format. Cron times are interpreted in the listener's TZ (tell user what TZ they're configured for: grep ^TZ= .env).
Step 5 — Boundaries + work hours (config.json)
From the template config.json. Customize:
boundaries: ask "Should this agent be read-only or have write access?" Read-only restricts toRead,Grep,Glob,WebSearch,WebFetch— useful for analysts, monitors. Write is the default and gets the full tool set.work_hours: informational only — it does not restrict when the agent answers inbound messages; those are always answered 24/7. Ask "What hours is this agent meant to be relevant, for the record?" and setenabled: truewith start/end/days if the user wants that documented. Defaultenabled: false. If the user actually wants the agent quiet outside certain hours, that has to be encoded in the routine's cron (Step 4) instead.model: leave default unless the user has a preference.
Step 6 — Slack app
Each agent has its own Slack app. Two paths — pick automatically based on .env:
# Read .env once at the start of Step 6
grep -E '^(SLACK_CONFIG_TOKEN|SLACK_CONFIG_REFRESH_TOKEN|SLACK_WORKSPACE_URL)=' .envIf SLACK_CONFIG_TOKEN and SLACK_CONFIG_REFRESH_TOKEN are both set → programmatic path (6A). Otherwise → manual path (6B).
Step 6A — Programmatic (when config tokens are configured)
This path generates the Slack app with all 13 scopes, Socket Mode, and 4 event subscriptions in one API call. The user then does ~3 manual clicks (install, copy bot token, generate App-Level Token, upload icon). Saves ~17 clicks compared to manual.
1. Get a valid access token via the rotation helper.
ACCESS=$(bash scripts/rotate-slack-config-token.sh) || exit 1
# stderr from the script tells you what failed; if it's "invalid_refresh_token",
# the chain is broken — regenerate the pair at https://api.slack.com/apps
# (bottom of page → "Your App Configuration Tokens") and update .env.Always use the helper. Never call tooling.tokens.rotate directly. Every successful rotation invalidates the previous refresh token. If a caller rotates inline and crashes / forgets to write back the new pair, the workspace loses access to the config-token API entirely (refresh dead, can't bootstrap without manual regen). scripts/rotate-slack-config-token.sh binds rotation and atomic persistence into one operation — writes to .env.new, then os.replace (POSIX-atomic rename). Any caller who receives an access token from it is guaranteed the new pair is already on disk.
2. Build the manifest for this agent. The canonical shape lives in templates/agent/slack-manifest.json — substitute {{AGENT_NAME}} and {{ROLE_DESCRIPTION}} and you're done. Mirrored from a known-working production manifest. Don't add redirect_urls — that switches the app into the distributed-OAuth flow and breaks the workspace install-on-team button.
For reference, the manifest the skill writes:
{
"display_information": {
"name": "<AGENT_NAME>",
"description": "<one-line role from Step 1>",
"background_color": "#2c3e50"
},
"features": {
"app_home": {
"home_tab_enabled": false,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"bot_user": {
"display_name": "<AGENT_NAME>",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read", "chat:write", "chat:write.customize",
"chat:write.public", "channels:history", "channels:read",
"groups:history", "groups:read", "im:history", "im:read",
"im:write", "users:read", "files:read", "files:write"
]
},
"pkce_enabled": false
},
"settings": {
"event_subscriptions": {
"bot_events": ["app_mention", "message.channels", "message.groups", "message.im"]
},
"interactivity": { "is_enabled": true },
"org_deploy_enabled": false,
"socket_mode_enabled": true,
"token_rotation_enabled": false,
"is_mcp_enabled": false
}
}3. Create the app via manifest:
curl -s -X POST https://slack.com/api/apps.manifest.create \
-H "Authorization: Bearer $ACCESS" \
-H "Content-Type: application/json; charset=utf-8" \
-d "{\"manifest\": $(cat manifest.json | jq -c 'del(._comment)')}" \
| tee /tmp/manifest-resp.jsonCapture app_id from the response. If ok: false, surface the error to the user and abort.
4. Send the user the install URL. Ignore the oauth_authorize_url returned by apps.manifest.create — that's the distributed-app OAuth flow and it requires redirect_urls we deliberately omitted. Use the app management page's install button instead:
https://api.slack.com/apps/<APP_ID>/install-on-team"Click here to install <AGENT_NAME> in your workspace:
https://api.slack.com/apps/<APP_ID>/install-on-team— click Install to Workspace, then Allow."
The user must click. Slack does not allow programmatic install for workspace-scoped apps. After Allow, they land on the app's OAuth & Permissions page where the bot token is now visible — perfect timing for the next step.
5. After install, the user manually copies tokens. Slack does NOT return the bot token in any API response after install. The user has to go fetch it:
"Once installed, go to https://api.slack.com/apps/<APP_ID>/oauth — copy the Bot User OAuth Token (
xoxb-…) and paste it here."
"Then go to https://api.slack.com/apps/<APP_ID>/general — scroll to App-Level Tokens → click Generate Token and Scopes. Name:
<AGENT_NAME>-socket. Add all three scopes:connections:write(Socket Mode — required),authorizations:read, andapp_configurations:write(forward-compat for future framework features that may inspect installations or update app config). Click Generate. Copy thexapp-…token and paste it here."
6. Upload the icon. Slack does not expose a bot-icon-set API:
"Final step: go to https://api.slack.com/apps/<APP_ID>/general → Display Information → click Add App Icon → upload
agents/<slug>/avatar.png→ Save Changes."
Step 6B — Manual (when config tokens are not configured)
Walk the user through the full click-flow:
- Go to https://api.slack.com/apps → "Create New App" → "From scratch."
- App Name: the agent's name (Step 1). Workspace: the user's.
- Socket Mode → Enable. Generate App-Level Token — name
<AGENT_NAME>-socket. Add all three scopes:connections:write(Socket Mode),authorizations:read,app_configurations:write(forward-compat). Click Generate. Copy thexapp-…token. Save. - OAuth & Permissions → add bot scopes:
app_mentions:read,chat:write,chat:write.customize,chat:write.public,channels:history,channels:read,groups:history,groups:read,im:history,im:read,im:write,users:read,files:read,files:write. (Canonical list also intemplates/agent/slack.json.) - Event Subscriptions → Enable. Subscribe to bot events:
app_mention,message.channels,message.groups,message.im. Save. - Basic Information → Display Information → upload
agents/<slug>/avatar.pngas the App Icon. Save. - Install to Workspace → Allow.
- After install, OAuth & Permissions → copy the Bot User OAuth Token (
xoxb-…). - Paste both tokens (
xoxb-…andxapp-…) here.
After both paths — validate and capture IDs
curl -s -X POST https://slack.com/api/auth.test \
-H "Authorization: Bearer <xoxb-...>" | jqShould return ok: true with user_id and bot_id. Capture user_id (= bot_user_id, U…) and bot_id (B…).
For the channel: have the user /invite the bot to the agent's channel, then look up its ID:
curl -s -X POST https://slack.com/api/conversations.list \
-H "Authorization: Bearer <xoxb-...>" -d 'types=public_channel,private_channel' \
| jq -r '.channels[] | "\(.id) \(.name)"' | grep '<channel_name>'Step 7 — Write all files
Now you have everything. Create agents/<slug>/ and write:
agents/<slug>/
├── PROMPT.md # from Step 3
├── SOUL.md # from Step 2
├── avatar.png # from Step 2.5 (already saved by user)
├── config.json # from Step 5
├── credentials.json # gitignored — slack tokens + any role-specific keys
├── slack.json # bot_user_id, bot_id, channel.id, app_id
├── schedules.json # from Step 4
├── memory/
│ ├── rules.md # empty header from template
│ ├── playbook.md # empty header from template
│ └── episodes/ # empty dir
└── skills/ # empty dir; user adds skills hereCopy from templates/agent/, then substitute. Don't forget:
credentials.json={ "slack_bot_token": "xoxb-...", "slack_app_token": "xapp-..." }plus any role-specific keys the user mentioned (Stripe, Supabase PAT, etc.).- The CHANNEL_ID placeholder in PROMPT.md gets filled now.
Step 8 — Register in the team directory
Use the manage-known-users skill flow:
- Should this agent be visible to
(a) all agents,(b) specific agents, or(c) no agents? - Write to the right known-users.json file(s) with:
{ "<bot_user_id>": { "kind": "agent", "name": "<agent name>", "short_name": "<agent name>", "title": "<role>", "role": "agent", "channel": "<channel_id> (#<channel_name>)", "responsibilities": "<from PROMPT.md>", "authority": "<read-only / write / case-by-case>" } }
Step 9 — Restart listener
pm2 restart ginnie-agents-listener --update-envTail and verify:
pm2 logs ginnie-agents-listener --lines 20 --nostreamExpected: Started: <agent> (bot: <bot_user_id>, channel: <channel_id>).
Step 10 — Smoke test
Have the user @<agent> in the channel with a simple greeting. Confirm:
- The agent responds within ~30 seconds.
- The reply matches the agent's voice (SOUL is working).
- Check the listener log for the matching
[@mention]and[<agent>] Container donelines.
If no response in 60 seconds:
- Check
pm2 logs ginnie-agents-listenerfor errors. - Verify the bot is
/invited to the channel. - Verify Socket Mode is enabled and
xapp-token hasconnections:write. - Verify
auth.teststill returnsok: true.
Step 11 — Confirm with the user
Tell them:
- Agent created, registered, running.
- Voice came from SOUL.md — show them the path so they can edit personality without reopening this skill.
- Routines: where to find / edit (
schedules.json+manage-routinesskill). - Memory: rules.md is the canonical place for "always do X" — the agent edits it the first time the user states a requirement.
- Suggest: tag the agent now with a real task to validate end-to-end.
Don't claim "done" until smoke test passes.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

