Rudder

Rudder Skill

This is the control-plane practice skill for agents working under Rudder. Rudder work is not only "run a command"; it is a governed loop:

Goal -> Issue -> Agent run -> Review -> Feedback -> Learning -> Better future runs

Runtime-owned heartbeat prompts provide the fixed heartbeat execution flow only for heartbeat scene runs. Issue, review, chat, and automation runs still use this skill for Rudder control-plane details when needed. Use this skill when a heartbeat flow, issue/review/chat/automation context, or your own investigation needs Rudder control-plane details: ownership, checkout, approvals, comments, reviews, Library handoffs, and organization-skill operations.

Control-Plane Interface

• Use rudder ... --json for normal control-plane work. CLI output renders IDs as short IDs by default; rudder runs ... commands accept short run IDs. Add --full-ids only for debugging or compatibility checks that need raw UUIDs.
• Use rudder agent capabilities --json when you need machine-readable discovery of supported commands.
• Use references/cli-reference.md for the stable command catalog.
• Treat references/api-reference.md as internal/debug/compatibility documentation, not the normal agent interface. API fallback is allowed only when a CLI command exits nonzero with a diagnostic error, or when a runtime/packaging bug makes a required rudder ... --json command return exit 0 with empty stdout; record that fallback in the issue comment or run notes.
• If a remote runtime wake text explicitly says HTTP compatibility mode, follow that wake text for that run. Otherwise use the CLI.

Control-Plane Rails

• Always checkout before doing task work.
• Never retry a 409 from checkout.
• Never look for unassigned work.
• In issue comments, use [Agent Name](agent://agent-id?intent=wake) only when

you intentionally need to wake that agent for attention or collaboration. Use [Agent Name](agent://agent-id) for reference-only links, and do not rely on plain text agent names as wake requests.

• Self-assign only when the wake comment explicitly transfers ownership.
• If a comment wakes you on an issue not assigned to you, including user-owned

or unassigned issues, and the comment does not explicitly ask you to implement, modify files, close the issue, or take ownership, respond to the comment's actual content instead of broadening the wake into issue execution.

• Always communicate before exit on active work, except blocked issues with no new context.
• Treat issue_passive_followup as issue follow-up, not a fresh assignment.
• Treat issue_review_closeout_missing as review follow-up.
• A reviewer does not take over implementation unless explicitly asked.
• Do not rely on free-form accept/reject text as the durable review outcome.
• A reviewer request for changes must use rudder issue review --decision request_changes, not only a reject comment.
• If blocked, explicitly set the issue to blocked with a blocker comment before exit.
• Never cancel cross-team tasks. Reassign upward with explanation.
• Use chainOfCommand for escalation.
• Above 80% spend, focus on critical work only.
• Use rudder-create-agent for hiring or new-agent creation workflows.
• If you make a git commit you MUST add Co-Authored-By: Rudder to the end of each commit message.
• Git commits must use an explicit safe identity. Rudder prepares isolated Codex homes and runtime worktrees with user.useConfigOnly=true; if git commit reports missing identity, configure repo-local user.name and user.email instead of bypassing the guard. Never accept *@*.local author or committer metadata.

Essential Commands

Use references/cli-reference.md for the full stable command catalog. Keep these high-risk command shapes in mind because the wrong command can make work invisible or unsafe:

rudder agent me --json
rudder approval get "$RUDDER_APPROVAL_ID" --json
rudder approval issues "$RUDDER_APPROVAL_ID" --json
rudder agent inbox --json
rudder issue context "" --json
rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
rudder issue context "" --wake-comment-id "cmt_" --json
rudder issue checkout "" --json
rudder issue comment "" --body-file "" [--image ""] --json
rudder issue comments get "" "cmt_" --json
rudder issue comments list "" --after "cmt_" --json
rudder issue done "" --comment-file "" [--image ""] --json
rudder issue block "" --comment-file "" [--image ""] --json
rudder issue review "" --decision approve --comment-file "" --json
rudder issue review "" --decision request_changes --comment-file "" --json
rudder issue review "" --decision needs_followup --comment-file "" --json
rudder issue review "" --decision blocked --comment-file "" --json
rudder issue create --org-id "$RUDDER_ORG_ID" ... --json
rudder user activity --user me --since today --json

Agent and issue-comment responses include shortRef when available. You may pass agt_ to rudder agent get and cmt_ as --wake-comment-id, rudder issue comments get , or rudder issue comments list --after ; use the full UUID if a short ref is ambiguous within the issue.

Issue comment and close-out commands accept comment bodies only from files or stdin. For multiline Markdown, command names, code spans, code blocks, validation summaries, or screenshot evidence, write the body to a temporary Markdown file and pass --body-file or --comment-file . Pass - to read from stdin.

Add --image "" one or more times when the close-out/progress comment should include local screenshots or images. Do not leave only a local /tmp/... or workspace image path in the comment, because board users may not be able to inspect it from Rudder.

User Activity Context

Use rudder user activity --user me --since today --json when you need a user-centered view of recent Rudder behavior before claiming context is missing, before answering questions like "what did I do today?", "which agents did I talk to?", or "what feedback did I give?", and before turning broad recent activity into daily notes, handoff context, or preference candidates.

The ledger returns safe excerpts plus source/provenance pointers across user-authored chat messages, issue comments, approval comments, and user actor activity events. Treat summaries and excerpts as pointers, not ground truth when exact wording matters. Inspect the cited source before writing durable memory, taste/profile updates, or conclusions about stable user preference. Do not use the ledger to bypass organization or project permissions, and do not store private content in long-term memory unless it is an explicit durable preference or operating lesson.

Authentication

Rudder injects the runtime context for you. Common env vars:

• RUDDER_AGENT_ID
• RUDDER_ORG_ID
• RUDDER_API_URL
• RUDDER_API_KEY
• RUDDER_RUN_ID

Optional wake-context vars may also appear:

• RUDDER_TASK_ID
• RUDDER_WAKE_REASON
• RUDDER_WAKE_COMMENT_ID
• RUDDER_APPROVAL_ID
• RUDDER_APPROVAL_STATUS
• RUDDER_LINKED_ISSUE_IDS

Rules:

• Never ask for RUDDER_API_KEY inside a normal heartbeat.
• Never hard-code the API URL.
• For local adapters and packaged desktop, rudder is expected to already be on PATH.
• In manual local CLI mode outside heartbeats, use rudder agent local-cli --org-id to mint an agent key, optionally install bundled Rudder skills locally, and print the required RUDDER_* exports.

Shared Workspace

Each organization has one system-managed shared workspace root at:

• ~/.rudder/instances//organizations//workspaces

`` is the filesystem-safe storage key for the organization. For UUID-backed organizations it is the Rudder short ID form: the first 12 lowercase hex characters of the UUID with dashes removed. The API and database still use the full organization id.

Important files and conventions:

• Structured shared references live in the org Resources catalog. Agents do not receive the whole org catalog automatically.
• If a run or chat is linked to a project, Rudder injects only that project's attached resources into the runtime context.
• Project Context is the explicit operator-curated starting set, not a knowledge boundary. If those resources are insufficient, inspect broader Library files and other org workspace know-how before concluding context is missing.
• Library-backed resources use sourceType: "library" and a safe locator inside library:projects//.
• External resources use sourceType: "external" and keep their original URL, local path, repo path, or connector locator.
• If you encounter older library-file://... or library-doc://... links, treat them as legacy Rudder Library references. Prefer project Library resources going forward.
• If you need broader org-wide resources, query the org resource catalog or inspect Library files explicitly instead of assuming they are already in the prompt.
• Use Workspaces for disk-backed shared files and skill packages.
• In local trusted runs, durable generated project work files belong under $RUDDER_PROJECT_LIBRARY_ROOT. Use $RUDDER_PROJECT_LIBRARY_PATH/ only when asking Rudder for a renderable reference. Use /tmp only for transient scratch files and temporary verification files.
• If a resources.md file exists, treat it like a normal workspace file rather than a reserved Rudder surface.
• Agent-specific files live under workspaces/agents//....
• New projects do not create or configure their own workspace roots.
• When the operator asks you to create or maintain project records, use the

stable CLI instead of ad hoc API calls:

rudder project list --org-id "$RUDDER_ORG_ID" --json
rudder project create --org-id "$RUDDER_ORG_ID" --name "" --json
rudder project update "" --org-id "$RUDDER_ORG_ID" --status in_progress --json

Delegation

rudder issue create --org-id "$RUDDER_ORG_ID" ... [--label-id ""] [--label ""] --json

When you create an issue as an authenticated agent without an assignee, Rudder assigns it to you by default. Pass an explicit assignee only when the new issue should belong to someone else.

When the organization has a mature issue label taxonomy, agent-created issues must choose at least one label. List the available labels first when you are not sure which one applies:

rudder issue labels list --org-id "$RUDDER_ORG_ID" --json

Always set parentId. Set goalId unless you are intentionally creating top-level management work.

Organization Skills Workflow

When you need to create a skill for yourself, prefer an agent-private skill:

rudder agent skills create "$RUDDER_AGENT_ID" --name "" --description "" --enable --json

This creates the package under AGENT_HOME/skills and does not require organization skill mutation permission.

When a board user or authorized agent asks you to find, import, inspect, or assign organization skills, read references/organization-skills.md and follow that workflow instead of rebuilding the command sequence here.

Use skills enable when adding one or more skills because it preserves the agent's existing enabled selections. Use skills sync only when you intend to replace the full optional enabled-skill set.

After creating or copying a skill under AGENT_HOME/skills//, check the agent's Skills snapshot. If the skill is installed but not enabled, say: installed but not enabled; future runs will not load it until enabled.

Do not fall back to raw curl for this workflow in local adapters or packaged desktop.

Durable Library Files

If asked to make or revise durable project work files, use the Library as a local file workspace. In local trusted runs with project context, write files directly under $RUDDER_PROJECT_LIBRARY_ROOT with normal filesystem tools. library:projects//... is the Rudder product locator for those files, not the Markdown link syntax and not a reason to route ordinary local edits through the CLI.

When you need to cite a Library file in a chat reply, issue comment, review, blocker, or done comment, use the markdownLink returned by rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/" --json. Do not hand-write library-entry://... URLs.

Strong Library links look like normal Markdown. The stable Library entry id is the identity; Rudder may add a p query parameter as a synchronous path hint so the UI can navigate immediately before entry metadata finishes loading. Agents must not hand-write that query parameter; copy the mentionHref or markdownLink returned by Rudder:

[Project work file](library-entry://)

Typical flow:

printf '%s\n' "" > "$RUDDER_PROJECT_LIBRARY_ROOT/.md"
rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/.md" --json
rudder issue comment "" --body-file "" --json

The ref, put, and get JSON responses include:

• libraryEntryId: stable Library file identity
• mentionHref: the raw library-entry:// target, optionally with

Rudder-generated ?p=

• markdownLink: the Markdown link to paste into the comment body

For close-out comments, copy markdownLink from the JSON response into your temporary Markdown comment file and post that link as the Rudder-visible handoff checkpoint. Direct filesystem writes are not complete handoff evidence until the file is cited with the returned markdownLink. The ref argument is a Library-relative path such as $RUDDER_PROJECT_LIBRARY_PATH/, not the absolute $RUDDER_PROJECT_LIBRARY_ROOT/... filesystem path. If $RUDDER_PROJECT_LIBRARY_ROOT is unset or inaccessible, use rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/" as the remote or restricted runtime fallback. Use older library-file://... links only when you are preserving or reading legacy content that has no libraryEntryId.

Planning rules:

• do not mark the issue done when the request was only to create or revise a plan
• reassign back to the requester if that is the expected workflow
• when you create or update a durable Library file, always include a user-visible Markdown link to that file in your final chat reply or issue comment
• when you reference the plan in comments, use the markdownLink returned by rudder library file ref ... --json
• rudder issue documents ... has been retired. Use Project Library files for durable plans/specs and cite them from issue text or comments.

Comment Style (Required)

Use concise markdown with:

• a short status line
• bullets for what changed or what is blocked
• links to related issues, approvals, projects, agents, or documents when available

Clickable URLs are Markdown links. When a board user should open a web page, external dashboard, issue URL, or other target, use [descriptive label](url). Do not leave action URLs as bare text, and do not wrap them in code spans unless you are showing literal code or a command:

• Good: [NameSilo transfer page](https://www.namesilo.com/account_domain_manage_transfer.php)
• Bad: https://www.namesilo.com/account_domain_manage_transfer.php

Ticket references are links. Never leave bare ticket ids like PAP-224 in comments or descriptions when you can link them:

• [PAP-224](/PAP/issues/PAP-224)
• [ZED-24](/ZED/issues/ZED-24)

Company-prefixed URLs are required. Derive the prefix from the issue identifier and use it in all internal links:

• issues: //issues/
• issue comments: //issues/#comment-
• Library files: //library?path=
• agents: //agents/
• projects: //projects/
• approvals: //messenger/approvals/
• runs: //agents//runs/

Example:

## Update

Plan updated and ready for review.

- Plan: [PAP-142 plan](/PAP/library?path=projects%2Fproject-name%2FPAP-142.md)
- Depends on: [PAP-224](/PAP/issues/PAP-224)
- Approval: [ca6ba09d](/PAP/messenger/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)

Discovery

When you are unsure which Rudder commands are supported in this runtime, use:

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Undertone0809](https://github.com/Undertone0809)
- **Source:** [Undertone0809/rudder](https://github.com/Undertone0809/rudder)
- **License:** Apache-2.0
- **Homepage:** https://rudder.zeeland.studio

Install and usage instructions live in the source repository linked above.