agentleFS
nitaybznitaybz/ginnie-agents/.claude/skills/manage-known-users/SKILL.md

manage-known-users

Skill18 starsChanged 3 months agoMITView on GitHub

Add, edit, or remove humans and agents from the team directory (shared and per-agent known-users.json). Use when the user says "add user", "add a teammate", "remove user", "edit user", "manage known users", "register a person", or describes someone new on the team.

  • Sends data out

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the user said "add", go to Add.

    line 40
  2. Very specific:

    If the user can't find the ID and you have any agent's slack_bot_token available, you can search:

    line 48
  3. Distinctive:

    Don't proceed without a confirmed Slack ID.

    line 54
  4. Very specific:

    Only follow up if (b): "Which agents?" — list available agent names from the agents/ directory.

    line 62
  5. Distinctive:

    Don't ask for everything in one big question.

    line 70
  6. Very specific:

    Use jq to merge into existing files without losing other entries.

    line 78
  7. Very specific:

    When writing to agents/<n>/known-users.json for the first time:

    line 82
  8. Distinctive:

    Don't leak personal info (phone, address) into known-users — keep entries professional.

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Manage Known Users

The team directory has two layers, merged at runtime:

  • shared/known-users.json — visible to all agents (the default)
  • agents/<n>/known-users.json — visible only to that agent (selective visibility)

Same Slack ID in both → local entry wins for that key only. Otherwise union.

Schema

{
  "users": {
    "U0XXXXXXXXX": {
      "kind": "human",
      "name": "Full Name",
      "short_name": "First",
      "title": "Founder",
      "role": "founder",
      "email": "person@example.com",
      "responsibilities": "One-line summary of what this person owns",
      "authority": "What instructions from this person count as authoritative",
      "tone": "How agents should address this person"
    }
  }
}

For agents, kind: "agent" plus channel: "C0… (#name)" instead of email.

role is freeform but agents key off it. Common values: founder, support-engineer, partner, customer, agent, unknown, external, bot.

Step 1 — Decide: add, edit, or remove?

If the user said "add", go to Add. "Remove" / "delete" → Remove. "Edit" / "change" / "update" → Edit. If unclear, ask.

Step 2 — Resolve the Slack ID

The user almost never knows their teammate's Slack member ID. Help them find it:

  1. In Slack, click the person's profile → ⋮ menu → "Copy member ID" (starts with U).
  2. Paste it here.

If the user can't find the ID and you have any agent's slack_bot_token available, you can search:

curl -s -X POST https://slack.com/api/users.list \
  -H "Authorization: Bearer $TOKEN" | jq -r '.members[] | select(.profile.real_name | test("<name>"; "i")) | "\(.id) \(.profile.real_name) \(.profile.email // "no email")"'

Don't proceed without a confirmed Slack ID.

Step 3 (Add) — Visibility tree

ONE question, with three options:

Should this person be visible to (a) all agents, (b) specific agents only, or (c) no agents (you're just registering them in shared but they shouldn't appear in any team directory)?

Only follow up if (b): "Which agents?" — list available agent names from the agents/ directory.

Step 4 (Add) — Gather fields

For humans: name, short_name, title, role, email, responsibilities, authority, tone.

For other agents: name, short_name, title, role: "agent", channel, responsibilities, authority.

Don't ask for everything in one big question; offer reasonable defaults based on context. Confirm the assembled record before writing.

Step 5 (Add) — Write to the right file(s)

  • Visibility (a) → write to shared/known-users.json
  • Visibility (b) → write to each chosen agents/<n>/known-users.json (create the file if missing). Do NOT also write to shared.
  • Visibility (c) → write to shared/known-users.json but tell the user nothing renders this until at least one agent's local file references it.

Use jq to merge into existing files without losing other entries. Pretty-print on save.

Step 6 (Add) — Create per-agent file if needed

When writing to agents/<n>/known-users.json for the first time:

{ "users": {} }

Then merge in the new entry.

Step 7 (Edit) — Find the entry

Show all matches across shared/ and per-agent files. Ask which one to edit. Re-prompt for fields with current values as defaults.

Step 8 (Remove) — Find and confirm

grep -l "U0XXXXXXXXX" shared/known-users.json agents/*/known-users.json

Confirm with the user before removing — multiple agents may reference this person.

Step 9 — Restart listener

shared/known-users.json is loaded at listener startup; per-agent files are read on demand and cached. To pick up changes immediately:

pm2 restart ginnie-agents-listener --update-env

Tell the user the change is live.

Notes

  • The kind field drives whether the entry shows up under "Humans" or "Agents" in the rendered team directory.
  • Don't leak personal info (phone, address) into known-users — keep entries professional.
  • For agents, the bot_user_id (from agents/<n>/slack.json) IS the Slack ID to use as the key.

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.