agentleFS
shahshreyshahshrey/unclaw/.claude/skills/setup/SKILL.md

setup

Skill17 starsChanged 7 months agoMITView on GitHub

Bootstrap an UnClaw agent from scratch. Converts a stock Claude Code instance into a persistent personal agent with identity, memory, and scheduling.

  • Pipes a download into a shell
  • Reads credentials

191 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-voice-transcription, add-discord and 10 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.
  • juancruzmunozalbeloSkill

    add-voice-transcription

    Add voice message transcription to NanoClaw using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them.

    Also in 5 projects that use this

  • MicrosoftSkill

    add-discord

    Add Discord bot channel integration via Chat SDK.

    Also in 11 projects that use this

  • MicrosoftSkill

    add-slack

    Add Slack channel integration via Chat SDK.

    Also in 11 projects that use this

  • juancruzmunozalbeloSkill

    add-telegram-swarm

    Add Agent Swarm (Teams) support to Telegram. Each subagent gets its own bot identity in the group. Requires Telegram channel to be set up first (use /add-telegram). Triggers on "agent swarm", "agent teams telegram", "telegram swarm", "bot pool".

    Also in 7 projects that use this

  • +8 more from microsoft

The file

Show its rules and text

We split this skill into the rules it gives an agent

44 rules. 0 are common, 18 are distinctive, and 26 are very specific to this project.

  • 0

    Common

    Most of the 168 edited versions we read keep these.

  • 18

    Distinctive

    This author's own choices. Worth a look.

  • 26

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ensure these directories exist:

    line 14
  2. Distinctive:

    Ensure these critical files exist:

    line 23
  3. Very specific:

    If .claude/settings.json is missing or malformed, recreate it from templates/settings.json.

    line 35
  4. Very specific:

    Verify these required hooks exist in .claude/settings.json:

    line 37
  5. Very specific:

    If any are missing, repair .claude/settings.json from templates/settings.json.

    line 44
  6. Distinctive:

    Ensure scripts are executable:

    line 46
  7. Distinctive:

    Ask the user for:

    line 53
  8. Distinctive:

    Keep it concise (under 20 lines).

    line 91
  9. Very specific:

    Use config/agent.env as the source of truth for runtime config:

    line 93
  10. Distinctive:

    Ask: "Do you want to connect a messaging channel like Telegram?"

    line 100
  11. Distinctive:

    If yes, walk through the prerequisites first, then configure the channel.

    line 102
  12. Very specific:

    Check ~/.claude/settings.json for "DISABLE_TELEMETRY": "1" in the env object.

    line 110
  13. Very specific:

    If present, remove it. Claude Code uses feature flags for channels, and this setting causes --channels to fall back to "Channels are not …

    line 111
  14. Distinctive:

    If installed, tell the user which version is present and move on.

    line 117
  15. Very specific:

    If not found, install it with curl -fsSL https://bun.sh/install | bash, then verify with bun --version.

    line 118
  16. Distinctive:

    Wait for the user to provide the token before proceeding.

    line 128
  17. Very specific:

    Check if the Telegram plugin is already installed by running claude plugin list 2>&1 | grep -i telegram or checking …

    line 132
  18. Distinctive:

    If already installed and enabled, tell the user it's present and move on.

    line 134
  19. Distinctive:

    If not installed, tell the user to run these in a Claude Code session:

    line 135
  20. Very specific:

    If running inside Cursor rather than the Claude Code CLI, add the Telegram MCP server entry to .cursor/mcp.json instead (see the plugin's …

    line 140
  21. Distinctive:

    After either path, verify the Telegram plugin appears in the installed list.

    line 142
  22. Very specific:

    Create the per-agent state directory: ~/.claude/channels/telegram-<agent-name>/ (e.g.

    line 151
  23. Very specific:

    Create ~/.claude/channels/telegram-<agent-name>/.env with TELEGRAM_BOT_TOKEN=<token>

    line 153
  24. Very specific:

    Write these lines into config/agent.env:

    line 158
  25. Distinctive:

    After the agent is started and Telegram is connected:

    line 170
  26. Very specific:

    Ask the user to paste the pairing code (a short hex string like 25255d).

    line 173
  27. Very specific:

    Read ~/.claude/channels/telegram-<agent-name>/access.json to find the pending entry matching that code.

    line 174
  28. Very specific:

    Add the senderId to the allowFrom array and remove it from pending.

    line 176
  29. Very specific:

    Write the updated access.json.

    line 177
  30. Very specific:

    Create the approval notification: mkdir -p ~/.claude/channels/telegram-<agent-name>/approved then write the senderId to …

    line 178
  31. Very specific:

    Do not rely on /telegram:access pair for per-agent setups.

    line 183
  32. Distinctive:

    If the user doesn't have the code yet or the pending entry hasn't appeared, wait a moment and re-read the file.

    line 187
  33. Very specific:

    If no, leave AGENT_CHANNEL="" and TELEGRAM_STATE_DIR commented out in config/agent.env — tmux-only mode is valid.

    line 189
  34. Distinctive:

    Ensure it contains the required hooks listed in Step 0

    line 196
  35. Very specific:

    If not, overwrite it from templates/settings.json

    line 197
  36. Distinctive:

    Ask: "Do you want automatic heartbeats, session logging, memory promotion, nightly self-improvement, and watchdog restarts via launchd?"

    line 202
  37. Distinctive:

    Read the chosen session name and project directory

    line 205
  38. Very specific:

    Write them to ~/Library/LaunchAgents/

    line 210
  39. Very specific:

    If the assistant job exits with Operation not permitted or exit code 126, tell the user to grant Full Disk Access to /bin/bash in System …

    line 214
  40. Very specific:

    If no, skip — the agent still works, but recurring tasks must be run manually or via /loop.

    line 216
  41. Very specific:

    Check tmux session exists: tmux has-session -t <session>

    line 230
  42. Very specific:

    Check .claude/settings.json exists and includes the required hooks

    line 231
  43. Very specific:

    If launchd was enabled, verify the jobs are loaded: launchctl list | grep <session>

    line 236
  44. Distinctive:

    if Telegram is set up, confirm the pairing worked and the bot responds

    line 244

“Common” is measured: kept by at least 6 in 10 of the 168 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

Agent Setup

This skill bootstraps the entire agent. Do not assume hooks, launchd jobs, or even .claude/settings.json already exist.

Step 0: Install or repair the core scaffold

Before personalizing anything:

  1. Ensure these directories exist:
    • .claude/
    • .claude/rules/
    • .claude/skills/
    • .claude/scripts/
    • .claude/runtime/launchd/
    • memory/
    • daily-logs/
  2. Ensure these critical files exist:
    • CLAUDE.md
    • identity/SOUL.md
    • identity/user.md
    • identity/memory.md
    • config/agent.env
    • .claude/settings.json
    • .claude/rules/*.md
    • .claude/scripts/*.sh
    • templates/settings.json
    • templates/launchd/*.plist
  3. If .claude/settings.json is missing or malformed, recreate it from templates/settings.json.
  4. Verify these required hooks exist in .claude/settings.json:

    • SessionStart
    • Notification
    • PreCompact
    • PostCompact
    • PostToolUse

    If any are missing, repair .claude/settings.json from templates/settings.json.

  5. Ensure scripts are executable:
    chmod +x bin/start-agent.sh bin/setup.sh .claude/scripts/*.sh

Step 1: Gather identity and role

Ask the user for:

  • Agent name (e.g. "Ray", "Jarvis", "Friday")
  • Owner name and full name
  • Agent role — what this agent is. Not just "engineer." Could be: software engineer, research assistant, content creator, financial analyst, habit coach, food/nutrition tracker, writing partner, ops/devops specialist, data analyst, product manager, or anything else. Let the user type a custom role. This determines the agent's identity, expertise framing, and domain-specific rules.
  • Domain expertise — the equivalent of "tech stack" but for any role. Examples:
    • Software engineer → "TypeScript, React, Node.js"
    • Financial analyst → "equity research, DCF modeling, Bloomberg"
    • Content creator → "SEO, WordPress, video editing, social media"
    • Habit coach → "behavioral psychology, habit tracking, accountability"
    • Research assistant → "academic papers, literature review, citation management"
  • Timezone
  • OS
  • Editor
  • Communication style

Step 2: Personalize files

Replace placeholders in:

  • CLAUDE.md — {{AGENT_NAME}}, {{OWNER_NAME}}, {{AGENT_ROLE}}
  • identity/SOUL.md — {{AGENT_NAME}}, {{OWNER_NAME}}, {{AGENT_ROLE}}
  • identity/user.md — {{OWNER_NAME}}, {{OWNER_FULL_NAME}}, {{TIMEZONE}}, {{DOMAIN_EXPERTISE}}, {{OS}}, {{EDITOR}}, {{COMMUNICATION_STYLE}}
  • config/agent.env — AGENT_SESSION_NAME (lowercase agent name), AGENT_CHANNEL
  • .claude/rules/communication.md — {{OWNER_NAME}}
  • .claude/skills/daily-standup/SKILL.md — {{OWNER_NAME}}
  • .claude/skills/distill-session/SKILL.md — {{OWNER_NAME}}
  • .claude/skills/search-memory/SKILL.md — {{OWNER_NAME}}

Generate .claude/rules/domain.md

Generate this file based on the chosen role and domain expertise. It should contain role-appropriate conventions and best practices. Examples:

  • Software engineer → coding conventions, testing practices, linting rules
  • Content creator → tone guides, SEO checklist, publishing workflow
  • Financial analyst → data sourcing rules, model conventions, disclosure practices
  • Research assistant → citation style, source evaluation criteria, note-taking format
  • Habit coach → tracking format, check-in cadence, encouragement style
  • Any role → the file should feel like a senior practitioner wrote their working standards

Keep it concise (under 20 lines). The user can always expand it later.

Use config/agent.env as the source of truth for runtime config:

  • AGENT_SESSION_NAME → lowercase agent name
  • AGENT_CHANNEL → blank by default, filled if messaging is configured
  • TELEGRAM_STATE_DIR → per-agent path, set only if Telegram is configured

Step 3: Messaging channel (optional)

Ask: "Do you want to connect a messaging channel like Telegram?"

If yes, walk through the prerequisites first, then configure the channel.

Prerequisites

Handle these before configuring the channel. Do each silently and report the result to the user.

1. Claude Code channels

Check ~/.claude/settings.json for "DISABLE_TELEMETRY": "1" in the env object.

  • If present, remove it. Claude Code uses feature flags for channels, and this setting causes --channels to fall back to "Channels are not currently available."
  • Also check shell profiles for DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. If either is exported there, remove it and restart the terminal.

2. Bun

The Telegram MCP server runs on Bun. Run bun --version to check.

  • If installed, tell the user which version is present and move on.
  • If not found, install it with curl -fsSL https://bun.sh/install | bash, then verify with bun --version. Tell the user it was installed.

3. Telegram bot token

The user needs to create a bot through BotFather — this is the one step that requires manual action on their phone/desktop. Tell the user:

Open @BotFather on Telegram and send /newbot. It asks for a name (display name, anything) and a username (must end in bot, e.g. my_assistant_bot). BotFather replies with a token like 123456789:AAHfiqksKZ8... — copy the whole thing including the number and colon, and paste it here.

Wait for the user to provide the token before proceeding.

4. Telegram plugin

Check if the Telegram plugin is already installed by running claude plugin list 2>&1 | grep -i telegram or checking ~/.claude/plugins/installed_plugins.json.

  • If already installed and enabled, tell the user it's present and move on.
  • If not installed, tell the user to run these in a Claude Code session:
    /plugin install telegram@claude-plugins-official
    /reload-plugins
    If running inside Cursor rather than the Claude Code CLI, add the Telegram MCP server entry to .cursor/mcp.json instead (see the plugin's README for the server command and args).

After either path, verify the Telegram plugin appears in the installed list. Tell the user the result. Also verify if the Telegram MCP server appears in the active MCP list.

Per-agent Telegram isolation

Each agent gets its own Telegram state directory so multiple agents can run different bots on the same machine without conflict. The Telegram MCP plugin reads TELEGRAM_STATE_DIR from its environment; config/agent.env vars are auto-exported via set -a in the session scripts, so child processes (including MCP servers) inherit them.

  1. Create the per-agent state directory: ~/.claude/channels/telegram-<agent-name>/ (e.g. telegram-tony, telegram-ray — lowercase agent name)
  2. Create ~/.claude/channels/telegram-<agent-name>/.env with TELEGRAM_BOT_TOKEN=<token>
  3. Create ~/.claude/channels/telegram-<agent-name>/access.json with:
    {"dmPolicy": "pairing", "allowFrom": [], "groups": {}, "pending": {}}
  4. Write these lines into config/agent.env:
    AGENT_CHANNEL="plugin:telegram@claude-plugins-official"
    TELEGRAM_STATE_DIR="$HOME/.claude/channels/telegram-<agent-name>"

Why per-agent dirs? The Telegram MCP plugin defaults to ~/.claude/channels/telegram/ for its bot token and access list. If two agents share that path, they fight over the same bot token (409 Conflict) and share access lists. TELEGRAM_STATE_DIR overrides this per-agent.

Auto-pair the owner's Telegram account

After the agent is started and Telegram is connected:

  1. Tell the user: "DM your bot on Telegram now — send any message (e.g. 'hi'). The bot will reply with a pairing code."
  2. Ask the user to paste the pairing code (a short hex string like 25255d).
  3. Read ~/.claude/channels/telegram-<agent-name>/access.json to find the pending entry matching that code.
  4. Extract the senderId from the pending entry.
  5. Add the senderId to the allowFrom array and remove it from pending.
  6. Write the updated access.json.
  7. Create the approval notification: mkdir -p ~/.claude/channels/telegram-<agent-name>/approved then write the senderId to ~/.claude/channels/telegram-<agent-name>/approved/<senderId>. The bot polls this directory and sends a "Paired!" confirmation to the user.
  8. Tell the user they're paired — the bot will now respond to their DMs.

Do not rely on /telegram:access pair for per-agent setups. That command reads ~/.claude/channels/telegram/access.json instead of the per-agent directory. For isolated bots, pair by editing the per-agent access.json directly.

If the user doesn't have the code yet or the pending entry hasn't appeared, wait a moment and re-read the file. The bot writes the pending entry when it receives the first DM.

If no, leave AGENT_CHANNEL="" and TELEGRAM_STATE_DIR commented out in config/agent.env — tmux-only mode is valid.

Step 4: Hooks (required)

Hooks are required for daily logs, compaction safety, and indexing.

  1. Ensure .claude/settings.json exists
  2. Ensure it contains the required hooks listed in Step 0
  3. If not, overwrite it from templates/settings.json
  4. Confirm to the user that hooks are installed/repaired

Step 5: launchd scheduling (optional, macOS only)

Ask: "Do you want automatic heartbeats, session logging, memory promotion, nightly self-improvement, and watchdog restarts via launchd?"

If yes:

  1. Read the chosen session name and project directory
  2. Generate plists from templates/launchd/ by replacing:
    • {{AGENT_SESSION_NAME}}
    • {{PROJECT_DIR}}
    • {{AGENT_CHANNEL}}
  3. Write them to ~/Library/LaunchAgents/
  4. Validate them with plutil -lint
  5. Unload old versions if present, then launchctl load the new ones
  6. Verify with launchctl list | grep <session>
  7. If the assistant job exits with Operation not permitted or exit code 126, tell the user to grant Full Disk Access to /bin/bash in System Settings → Privacy & Security → Full Disk Access. Until then, they should start the agent manually after reboot.

If no, skip — the agent still works, but recurring tasks must be run manually or via /loop.

Step 6: Start the agent

./bin/start-agent.sh

Then verify the tmux session reaches the ❯ prompt. If Claude shows the workspace trust prompt, accept it and re-check the pane. If it shows "Channels are not currently available," go back to Step 3 prerequisite 1.

Step 7: Verify

  • Check tmux session exists: tmux has-session -t <session>
  • Check .claude/settings.json exists and includes the required hooks
  • Capture the tmux pane and confirm you see:
    • Listening for channel messages from: plugin:telegram@... (if Telegram enabled)
    • ❯ prompt (session is ready)
    • No "Channels are not currently available" warning
  • If launchd was enabled, verify the jobs are loaded: launchctl list | grep <session>

Step 8: Confirm

Tell the user:

  • how to attach: tmux attach -t <session>
  • which recurring tasks are automatic vs manual
  • that hooks are installed and daily logs/memory promotion will work
  • if Telegram is set up, confirm the pairing worked and the bot responds

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.