tloncorp/tlon-apps/tlon-skill

Operate Tlon

Use the tlon tool for Tlon data and administration. Read the task reference below before an unfamiliar workflow. For explanations of the app, use tlon-product-guide if available.

In Tlon requests, workspace means a group: create, join (including by invite link), rename, invite, and list workspaces using groups commands. Explicit requests about the agent’s files or paths refer to its filesystem workspace instead.

Invoke and discover

Tool arguments are argument strings, not shell scripts:

{"command":"help"}
{"command":"help notes"}
{"command":"help notes note-create"}

--help and -h also work. This help covers only commands in the Tlon index; other tools such as message, read, and write have their own tool schemas, not Tlon subcommands. Exact flags live in command help; inspect it instead of guessing a verb or copying flags from a different operation. If CLI usage shows tlon at the start, omit it in the tool's command argument.

There is no shell expansion, pipe, redirection, or stdin transport. Use write to create a content file and pass its filename. Relative paths resolve in the active agent workspace, just like read and write. Do not put $VARIABLE, a heredoc, or inline Markdown in a filename argument.

Choose the task reference

Resolve these links relative to this skill's discovered directory. Use the location in the available-skills listing; do not assume a particular installation path. Read only the reference needed for the task.

Identity, delivery, and completion

• Use returned group flags, channel nests, note IDs, and revisions. Display titles are not identifiers. Resolve ambiguous targets before writing.
• When a write lands outside the conversation you are replying in (a note, a post in another channel, a new group or channel, a cron job that will post to another channel), put a reference to it in your reply so Tlon renders a card. Forms: /1/group/<host>/<slug>, /1/chan/<nest>/msg/<id>, thread reply /1/chan/<nest>/msg/<parent>/<id>, /1/chan/notes/<host>/<name>/note/<id>. Prefer the Ref: path a command prints. A post's ID is host-assigned: read it back with messages channel <nest>, or messages post <nest> <parent> for a thread reply; the message tool's messageId is not it. A channel (including a cron job's target) has no card yet: name it, give its nest, and share its group's Ref:.
• Put the path bare on its own line after the sentence introducing it; a link, bold, or malformed path stays literal text. Paths render only in your normal reply; tlon posts send posts a typed path as literal text. To quote or forward a post as a card, use posts send|reply --quote or posts forward (see Reading).
• Before filling a saved website login, request fresh owner approval with browser approve-login; see Browser card commands. Do not use automatic-fill permission to skip approval. Existing signed-in browser sessions may be reused.
• Credentials are supplied by the runtime. Never collect access codes or print credentials. Your harness's tool description states which identity (your owner or you, the bot) is the default and how to select the other; follow it. Some commands are documented as owner-bound in the references; the tool description governs which identity they run as. Do not switch identities to work around a permission error.
• Use message for ordinary outbound messages and replies. For local media, upload first and pass the returned HTTPS URL. To post an image, file, video or link to a gallery, use posts send; see the media reference. A message sent under the owner's identity appears in the owner's name, exactly as if the owner had typed it (--bot adds only a Bot tag; it is still the owner's message): send one only when the owner explicitly asked for that message, and confirm with the owner first otherwise.
• A post someone asks to be pinged, tagged or @'d in has to contain their ~ship, which mentions and notifies them: "ping me in General" is a post in General that mentions them, and one without their ~ship pings nobody.
• Use groups create-owned to create a group for a user and make them an admin. Read the groups reference for the identity requirements.
• Markdown notebooks: a new notebook for a workspace is a group channel (channels create <group> "Title" --kind notes), and a request in a group channel means that group unless the user names another; notes create makes a standalone notebook outside every workspace. Use notes to read and write notes. Deprecated %diary management is unavailable through this tool; ask the owner to use /migrate <diary-nest> instead of attempting migration writes yourself.
• Do not use LaTeX delimiters in note bodies or messages; use plain text/Unicode or code blocks.
• Report a concrete failure if the task could not be completed. Verify the requested state before claiming success. A pending or host-confirmed write needs status/readback, not an immediate duplicate write.

When discovery fails

If this skill or a linked reference is unavailable, help and command help still provide local syntax. Report a missing installation resource rather than inventing a path. A permission failure or unsupported command is not a reason to bypass the tool through a shell, raw API, or the hosted browser. Never tell the user a Tlon command or capability does not exist without first running help and help <command>: the command index is authoritative and lists options these references omit. If neither tlon nor message covers the request, tell the user your Tlon tools do not support it yet and, where the Tlon app offers it, that they can do it there.