kuroko
Skill0 starsChanged 2 months agoMITView on GitHub
Manages, configures, and reconciles Telegram bots declaratively via the Kuroko (黒子) CLI. Use whenever inspecting bot fleets, updating bot command menus, editing bot bios/descriptions, syncing avatars/video covers, or creating new bots via BotFather.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- rules/AGENTS.mdAGENTS.md
- tayoriSkill
- xerjSkill
- aesthetic-readme-craftSkill
- cli-builderSkill
- codebase-digestSkill
- git-release-craftSkill
- git-repo-craftSkill
- karakuriSkill
- python-clean-codeSkill
- rust-clean-codeSkill
- rust-style-pythonSkill
- systematic-code-verificationSkill
- compose-clean-codeSkill
- bash-clean-codeSkill
- tui-designSkill
- frontend-designSkill
- web-design-guidelinesSkill
- unslopSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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
- Distinctive: line 54
When first running on a new machine or detecting an unmanaged bot on the system:
- Very specific: line 84
Zero Manual Editing: Never modify bots.toml using text replacement or manual file editing.
- Very specific: line 85
Safe Secrets (Zero Token Leaks): Always store bot tokens as environment references (e.g.
- Very specific: line 86
Verify Diffs Before Applying: Always run kuroko diff to inspect planned changes before executing kuroko apply.
- Very specific: line 87
Use
--http-onlyfor Headless Sync: When updating commands, descriptions, or names without interactive user terminal presence, always pass …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.
Files
kuroko (黒子) Telegram Bot Fleet Management Skill
Automates the configuration, command synchronization, and lifecycle management of Telegram bots through the kuroko CLI. Enables AI agents to manage bot fleets declaratively with zero manual TOML editing.
1. When to Use
- Inspecting Bot Fleet State: Querying registered bots, live usernames, command lists, and synchronization status (
kuroko list,kuroko cmd list <bot>). - Updating Bot Commands: Adding, modifying, or removing
/commanddescriptions when implementing new bot features in code (kuroko cmd add <bot> <cmd> "<desc>"). - Updating Bot Metadata: Updating bot display names, about text, short bios, or avatar media (
kuroko bot set <bot> ...). - Reconciling Desired vs Live State: Computing diffs against Telegram servers and applying changes (
kuroko diff,kuroko apply --http-only). - Auto-Discovering Host Bots: Automatically scanning host configuration files (
~/.config/ryoiki/telegram.json,~/.config/tayori/config.toml) and pulling live state (kuroko import --auto). - Provisioning New Bots: Automating
/newbotcreation dialogues with@BotFatherover MTProto (kuroko new).
2. Agent Usage & Command Patterns
A. Zero-Manual Configuration (Mutating bots.toml)
[!IMPORTANT] Never manually edit
bots.tomlfiles. Always use the dedicated CLI subcommands. Kuroko automatically resolves and updates~/.config/kuroko/bots.tomlby default.
# 1. Add or update a command for a bot
kuroko cmd add <bot_id> <command_name> "<description>"
# Example:
kuroko cmd add ryoiki status "Show system health, CPU, RAM, & active downloads"
kuroko cmd add ryoiki torrents "List active and completed torrents"
# 2. List currently configured commands for a bot
kuroko cmd list <bot_id>
# 3. Remove an obsolete command
kuroko cmd rm <bot_id> <command_name>
# 4. Set or update bot metadata
kuroko bot set <bot_id> \
--name "<Display Name>" \
--token "env:<TOKEN_ENV_VAR>" \
--desc "<Full long description>" \
--short-desc "<Short bio (max 120 chars)>"B. Auto-Importing Existing Host Bots
When first running on a new machine or detecting an unmanaged bot on the system:
# Auto-detects local bot tokens from known directories and pulls live state
kuroko import --auto
# Or import an individual bot by token
kuroko import --token "123456:ABC-DEF..." --id <bot_id>C. State Diffing & Deployment
# 1. Preview changes (diff local desired state vs live Telegram state)
kuroko diff
# 2. Apply changes immediately via Telegram Bot API (commands, descriptions, names)
kuroko apply --http-only
# 3. Full reconcile (including MTProto BotFather avatars/covers/privacy settings)
kuroko applyD. Fleet Overview Dashboard
kuroko list3. Operational Rules for AI Agents
- Zero Manual Editing: Never modify
bots.tomlusing text replacement or manual file editing. Usekuroko cmd add,kuroko cmd rm,kuroko bot set, orkuroko import. - Safe Secrets (Zero Token Leaks): Always store bot tokens as environment references (e.g.
env:RYOIKI_BOT_TOKEN,env:TAYORI_BOT_TOKEN) rather than hardcoding plaintext secrets in committed files. - Verify Diffs Before Applying: Always run
kuroko diffto inspect planned changes before executingkuroko apply. - Use
--http-onlyfor Headless Sync: When updating commands, descriptions, or names without interactive user terminal presence, always pass--http-onlyto avoid blocking on MTProto 2FA login prompts. - Keep Commands Synchronized With Code: Whenever adding a new bot command handler in application source code (e.g.
router.rs), immediately register the command in Kuroko:kuroko cmd add <bot_id> <new_command> "<Clear explanation>" kuroko apply --http-only
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.

