agentleFS
nitaybznitaybz/ginnie-agents/.claude/skills/create-agent/SKILL.md

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

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-agiSkill

    deploy-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-agiSkill

    setup-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

  • ElasticSkill

    create-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

  • MicrosoftSkill

    create-hook

    Create a hook (.json) to enforce policy or automate agent lifecycle events.

    Also in 5 projects that use this

  • AnasX7Skill

    improve

    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

  • ElasticSkill

    create-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

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
  1. Distinctive:

    Don't shortcut. The agent's quality follows from how carefully you elicit role, voice, schedule, and boundaries.

    line 10
  2. Distinctive:

    After drafting, show the full SOUL.md to the user before writing.

    line 35
  3. Very specific:

    If the user has a preferred image-creation skill installed (e.g., media-pipeline), suggest they invoke it with the derived prompt — but …

    line 52
  4. Very specific:

    Start from templates/agent/PROMPT.md.

    line 70
  5. Distinctive:

    Ask: does this agent have a routine?

    line 82
  6. Very specific:

    Use the manage-routines skill format.

    line 88
  7. Very specific:

    If SLACK_CONFIG_TOKEN and SLACK_CONFIG_REFRESH_TOKEN are both set → programmatic path (6A).

    line 106
  8. Very specific:

    After install, OAuth & Permissions → copy the Bot User OAuth Token (xoxb-…).

    line 212
  9. Very specific:

    Should return ok: true with user_id and bot_id.

    line 222
  10. Very specific:

    Use the manage-known-users skill flow:

    line 257
  11. Very specific:

    Should this agent be visible to (a) all agents, (b) specific agents, or (c) no agents?

    line 258
  12. Very specific:

    Write to the right known-users.json file(s) with:

    line 259
  13. Very specific:

    Check the listener log for the matching [@mention] and [<agent>] Container done lines.

    line 293
  14. Distinctive:

    If no response in 60 seconds:

    line 295
  15. Very specific:

    Check pm2 logs ginnie-agents-listener for errors.

    line 296
  16. Very specific:

    Verify the bot is /invited to the channel.

    line 297
  17. Very specific:

    Verify Socket Mode is enabled and xapp- token has connections:write.

    line 298
  18. Very specific:

    Verify auth.test still returns ok: true.

    line 299
  19. Distinctive:

    Don't claim "done" until smoke test passes.

    line 310

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. 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.
  2. Role / mission — one sentence: what does this agent own? E.g. "monitor the customer fleet and open tasks when machines go down."
  3. 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):

  1. 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."
  2. Life outside work — hobbies, weekends, recurring rituals. 3–5 sentences. Pick things that sound like a real person's calendar.
  3. Voice — sentence shape, language defaults, gender form (in gendered languages), emoji rules, banned words. Concrete: "short sentences, dry, never uses 'just' or 'super'."
  4. 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:

  1. The derived prompt (let them edit it).
  2. Required spec: square 1024×1024 PNG. Slack auto-crops to a circle, so the subject should be centered.
  3. 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 to TBD; 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.json empty ({"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 to Read, 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 set enabled: true with start/end/days if the user wants that documented. Default enabled: 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)=' .env

If 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.json

Capture 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, and app_configurations:write (forward-compat for future framework features that may inspect installations or update app config). Click Generate. Copy the xapp-… 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:

  1. Go to https://api.slack.com/apps → "Create New App" → "From scratch."
  2. App Name: the agent's name (Step 1). Workspace: the user's.
  3. 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 the xapp-… token. Save.
  4. 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 in templates/agent/slack.json.)
  5. Event Subscriptions → Enable. Subscribe to bot events: app_mention, message.channels, message.groups, message.im. Save.
  6. Basic Information → Display Information → upload agents/<slug>/avatar.png as the App Icon. Save.
  7. Install to Workspace → Allow.
  8. After install, OAuth & Permissions → copy the Bot User OAuth Token (xoxb-…).
  9. Paste both tokens (xoxb-… and xapp-…) here.

After both paths — validate and capture IDs

curl -s -X POST https://slack.com/api/auth.test \
  -H "Authorization: Bearer <xoxb-...>" | jq

Should 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 here

Copy 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:

  1. Should this agent be visible to (a) all agents, (b) specific agents, or (c) no agents?
  2. 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-env

Tail and verify:

pm2 logs ginnie-agents-listener --lines 20 --nostream

Expected: 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:

  1. The agent responds within ~30 seconds.
  2. The reply matches the agent's voice (SOUL is working).
  3. Check the listener log for the matching [@mention] and [<agent>] Container done lines.

If no response in 60 seconds:

  • Check pm2 logs ginnie-agents-listener for errors.
  • Verify the bot is /invited to the channel.
  • Verify Socket Mode is enabled and xapp- token has connections:write.
  • Verify auth.test still returns ok: true.

Step 11 — Confirm with the user

Tell them:

  1. Agent created, registered, running.
  2. Voice came from SOUL.md — show them the path so they can edit personality without reopening this skill.
  3. Routines: where to find / edit (schedules.json + manage-routines skill).
  4. Memory: rules.md is the canonical place for "always do X" — the agent edits it the first time the user states a requirement.
  5. Suggest: tag the agent now with a real task to validate end-to-end.

Don't claim "done" until smoke test passes.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.