Managing Scripts, Agents, and Skills in the Library

The Library sidebar stores reusable Sidekick assets that are shared across workspaces. A Library item can expose one or more entry points, and each entry point has a specific launch behavior:

• Python scripts run code.
• Agents create a new chat backed by an agent-specific completion pool (the smart pool is available by default).
• Skills inject reusable instructions into chat.

Use the Library when you want repeatable automation without retyping prompts, commands, or helper code.

Library items are stored per installation in Sidekick's application data, not in a workspace or a binary file, and the Library starts empty. Each item is a versioned folder; use Show in Finder (or the equivalent for your platform) to see it on disk. Sidekick's Authoring and Automation agents can also create Library items for you, as drafts (see How Sidekick Analyzes Binaries).

The Library sidebar

Open the Library sidebar from the Binary Ninja sidebar panel.

The sidebar uses the same two-surface layout as other Sidekick panels:

• Browse list shows Library items and supports search.
• Detail view shows the selected item's actions (Run, Run Agent, or Use Skill, and Commit...), the Revision selector, its Files list (with a default badge on the default entry point and the age of each file's last change), a README card that renders the item's root-level README.md when one exists, and the run output panel.

When the sidebar is narrow, the list and detail views share one pane. In that layout, choosing Run for a Python script automatically switches to the detail view before execution starts so the progress and output panels are visible.

Creating Library items

Create a new item from the Library browse view in either of two ways:

• Use the New Item flow and choose a starter template.
• Type into the Library composer to create an item directly.

The current starter templates are:

• Python Script — creates a new item with a starter Python entry point.
• Agent — creates a new item with a starter agent YAML definition.
• Skill — creates a new item with a starter skill file.
• Blank — creates an empty item you can populate yourself.

The composer supports these prefixes:

• @python My Script or @script My Script — create a Python Script item
• @agent My Agent — create an Agent item
• @skill My Skill — create a Skill item
• My Item — create a Blank item

Items you create from the Library sidebar, through either the starter templates or the composer, are published immediately. Items that Sidekick agents create for you (for example the Authoring and Automation agents), repositories re-added with Scan and Fix Library..., and scripts imported with Import 5.x Automation Workbench... start as Drafts. Clone Item keeps the draft or published state of the item it was cloned from.

Entry points and sidekick.yaml

Sidekick finds an item's entry points from its sidekick.yaml manifest if one exists. Otherwise it uses file conventions: main.py (or the only .py file) is a Python entry point, agent.yaml is an agent, and skills/*.md or skills/*.txt are skills. A single entry point is the default automatically; with several, set default_entry_point.

version: 1
default_entry_point: main
entry_points:
  main:
    kind: python        # python | agent | skill
    path: main.py
    title: Run
    description: What it does
    arguments_path: arguments.py   # python only, optional
  triage:
    kind: agent
    path: agents/triage.yaml

Files you create with Add File (Python Script, Agent, Skill) are registered in sidekick.yaml for you, and renaming or deleting them updates it.

Entry point types

Type	Primary action	Result
Python script	Run	Executes locally from the Library sidebar and shows progress/output in the item's detail view
Python script	Run in New Chat	Creates a chat and launches the script; Sidekick retrieves its outcome with wait_script before analyzing output
Agent	Run Agent	Creates a new chat process and a new main thread using the agent's configured completion pool
Skill	Use Skill	Imports the skill into the selected chat; if no chat is selected, Sidekick creates one first

The hamburger menu and browse-list context menu expose the launch actions for the selected entry point. The file context menu in the detail view offers the launch actions for entry points defined in that file.

Editing and versioning items

Selecting a Library item opens its detail view, which is the main editor for the item's working copy.

From the detail view you can:

• open a file from the Files list to edit it (use the file drop-down to switch files, Save to write the edit, and the back arrow to return to the overview)
• add new files with Add File
• choose from Empty File, Python Script, Agent, Skill, and Operator (a YAML file that defines a named LLM prompt template with a configurable completion pool, used for scripted completions outside the standard chat flow)
• commit your changes with Commit... (shown when the working tree has uncommitted changes); type a message and press Enter, or leave it blank to use Manual commit
• switch between the Working tree and earlier commits with the revision selector

Add File asks for a path (placeholders: scripts/new_script.py, agents/new_agent.yaml, skills/new_skill.md, operators/new_operator.yaml). A name without a folder is placed in agents/ (Agent), skills/ (Skill), or operators/ (Operator); Python Script and Empty File use the path as typed. .py, .yaml, or .md is appended when the extension is missing (skills may also end in .txt). Paths must be relative and cannot be inside tmp/; leaving the field blank uses the placeholder shown. The Agent option creates only a stub with name and description; add protocol_id, completion_pool_id, and prompt_template before running it. Operator is available only when the item has a Python entry point. If the item has several Python entry points, set a default Python entry point in sidekick.yaml to enable it.

Add a README.md at the root of an item to have it rendered on the item's overview.

Historical revisions are read-only. The current working tree remains editable.

The Revision drop-down on the overview lists each commit (short id, timestamp, and message) with a revision count beside it, so you can confirm the latest saved snapshots before switching revisions. Running an item saves unsaved edits first. You cannot switch revisions while a run is active, and you cannot switch to an earlier commit while files have unsaved edits (save or commit first).

Publishing, cloning, and file-manager actions

The Library distinguishes between draft and published items:

• Draft items are labeled with (Draft) in the sidebar.
• Use Publish to make a draft item part of the normal Library catalog.
• Use Revert to Draft to move a published item back into draft state.
• A successful local Run of a draft Python item publishes it automatically.

The hamburger menu and browse-list context menu also let you:

• Rename Item
• Clone Item (the copy is named <name> (Copy))
• Delete Item

Show in Finder, Show in Explorer, or Show in File Manager (depending on platform) is available from the browse-list context menu and, for individual files, from the file context menu in the detail view. The file context menu additionally offers Rename, Delete, and, for Markdown files, View as Markdown Report.

Library maintenance

The Library includes a maintenance workflow for catalog drift and stale storage:

• Use Scan and Fix Library... from the Library menu or maintenance button.
• Review Broken Items when the catalog still references a repository that no longer exists.
• Review Unindexed Library Repos when a library-managed repository exists on disk but is not in the Library catalog.
• Review Orphaned Filestore Repos when a filestore directory no longer has a matching FileRepository resource.

From the maintenance dialog, you can remove stale entries, add unindexed repositories back into the Library, or delete orphaned and unneeded repositories. Add to Library asks for an item name and adds the repository back as a draft.

Importing 5.x Automation Workbench scripts

Choose Import 5.x Automation Workbench... from the Library hamburger menu (or Plugins > Sidekick > Import 5.x Automation Workbench...) to import scripts from a Sidekick 5.x Analysis Workbench database as Library items. See Migrating from Sidekick 5.x for the full workflow.

Running Python scripts

Choose Run when you want to execute a script directly from the Library sidebar.

This path:

• runs the script locally instead of creating a chat
• keeps execution in the current Sidekick script runtime
• shows execution progress and output in the detail view
• is best for utility scripts where you want the raw output more than a conversation

When a Library Python script needs Sidekick workspace resources such as indexes, code maps, notebooks, prompts, or agents, import sidekick.api as api. See Scripting and Automation with the Sidekick API and Building and Using Indexes for the supported call patterns.

While a script launched with Run is executing, the Run button changes to Stop; click it to cancel the run. A script that calls notify_progress(...) is stopped there once cancellation has been requested. The output panel shows a status of Running, Done, Error, or Stopped and can be hidden with its close button.

Choose Run in New Chat when you want Sidekick to see the script output and continue from it.

This path:

• creates a new chat thread
• inserts a library_python_run tool call into that thread
• returns an execution handle; Sidekick uses wait_script to retrieve the final outcome
• lets Sidekick page through additional output with read_script_output and respond in the new chat
• is best when the script is part of a larger investigation

If Sidekick has not retrieved the outcome yet, ask it to check the script and analyze its output. The launch itself does not automatically insert all final output into the conversation.

Library Python scripts time out after 600 seconds by default, whether you choose Run or launch the script through chat. You can change the default with sidekick.execution.library_python_timeout in Binary Ninja's Sidekick settings. The optional timeout_override_seconds tool argument takes precedence over the setting when supplied; omit it or set it to null to use the setting. Overrides must be between 1 and 999999 seconds. Changes apply to new script runs without restarting Binary Ninja.

Running agents

Choose Run Agent to launch a Library agent as its own chat.

This path:

• creates a new chat/kernel process
• creates the first root thread for that process
• uses the agent's completion_pool_id from its YAML definition instead of the default Sidekick chat completer
• opens the Chats sidebar and selects the new chat automatically

An agent file is YAML. protocol_id, completion_pool_id, and prompt_template are required. Tool access is controlled by uses_tags; an agent that omits it runs without any tools. See Scripting and Automation with the Sidekick API for the full agent format.

Use agents when you want a reusable workflow that should start as its own conversation rather than being imported into an existing one.

Note

Running an agent requires an open workspace so Sidekick has a chat context to attach the new process to.

Using skills

Choose Use Skill to import a skill into chat.

This path:

• injects the rendered skill content into the active chat
• creates a new chat first if no chat is currently selected
• keeps you in the normal Sidekick chat flow instead of starting a separate agent process

Use skills when you want to steer an existing investigation with reusable instructions, checklists, or prompting patterns.

Launching Library items from chat

You can also launch the default entry point of a Library item directly from the Chat composer with a slash command.

• The command name is derived from the item name by lowercasing it and replacing punctuation or spaces with -. For example, Recover Strings becomes /recover-strings.
• Type // when you want to send a literal leading slash instead of launching a Library item.
• If an item has multiple entry points, set default_entry_point in sidekick.yaml before using it from chat.

The slash command behavior depends on the default entry point kind. All three kinds run inside the current chat (or a new one if no chat is selected) — Sidekick stays on the same conversation and weaves the result back into the thread:

• Python — /slug {json} schedules library_python_run in the current chat. /slug alone works when the script takes no arguments, or when the last saved or default arguments already validate; otherwise it requires JSON. Trailing text is rejected for scripts that take no arguments.
• Agent — /slug message works when the agent prompt defines a MESSAGE variable. Other agent prompts require /slug {json} whose keys match the agent's prompt_template.variables (typically uppercase, e.g. NAME, INSTRUCTIONS). Sidekick schedules a library_agent_run tool call in the current chat, launching the agent as a child thread of the current conversation and posting its final reply back into the parent chat.
• Skill — /slug {json} injects the rendered skill into the current chat. Skills without variables can be launched as /slug. For agents and skills with variables, bare /slug uses the last saved values or defaults when they satisfy the required variables. Plain trailing text is rejected for skills.

See Analyzing Binaries with Chat for the chat-side workflow and examples.

Runtime arguments

Scripts, agents, and skills can all declare runtime arguments. The Library presents them through a single workflow:

• If saved values or defaults already satisfy the entry point, the primary action runs immediately.
• If required values are missing, Sidekick opens an arguments dialog before launching.
• The ... With Arguments... actions (for example Run With Arguments... or Use Skill With Arguments...) always open the dialog, even when saved values exist. They appear only for entry points that declare arguments.
• The last accepted argument payload is saved per Library entry point and reused the next time you launch that same entry point.

Python script arguments

Python scripts opt into arguments with a companion arguments module: a Python file that defines a Pydantic model named ScriptArguments, referenced from the entry point's arguments_path in the item's sidekick.yaml.

When an entry point has an arguments_path:

• the dialog shows a JSON editor
• Sidekick validates the JSON against the script's schema before execution
• the same saved payload is reused for both Run and Run in New Chat

Entry points without an arguments_path run directly and never show the arguments dialog.

When arguments are declared, the script runs with the validated ScriptArguments instance bound to the global name args (for example args.target). Scripts run as top-level code, as in the Binary Ninja console, with bv bound to the active binary when one is open. Call notify_progress(step, total, message) to update the progress bar in the item's detail view; it raises KeyboardInterrupt if the run is cancelled. Other .py files in the item are importable from the entry point.

Agent arguments

Agent arguments come from prompt_template.variables in the agent YAML.

Each declared variable appears as a text field in the arguments dialog. Required fields must be filled before the agent launches.

Skill arguments

Skills can declare optional variables in a YAML prologue at the top of the skill document:

---
name: Example Skill
description: Analyze a target in a specific style
variables:
  TARGET:
    description: Function or subsystem to focus on
    required: true
  STYLE:
    description: Output style
    required: false
    default: concise
---
Analyze {{ TARGET }} in {{ STYLE }} form.

The prologue must be the first thing in the file, between two --- lines. Variables are required unless marked required: false, and an optional variable must supply a default.

Only declared variables are accepted. If the skill body references an undeclared placeholder, Sidekick treats that as a configuration error instead of guessing.

Choosing the right action

• Use Run for direct script execution when you mainly care about the script's own output.
• Use Run in New Chat when you want script execution plus Sidekick follow-up in a new chat.
• Use Run Agent when the item should start as its own specialized conversation.
• Use Use Skill when you want to guide the current investigation with reusable instructions.
• Use Publish when an item is ready for normal Library use, and Revert to Draft when you want to keep iterating on it without treating it as finalized.

Workspace Repositories

Sidekick Resources gives you access to workspace repositories: versioned file stores that belong to the current workspace rather than the application Library. Unlike Library items, workspace repositories are scoped to a single workspace (one per standalone file, with multiple workspaces available in projects) and are not shared across other workspaces.

How workspace repositories differ from Library items

	Library item	Workspace repository
Scope	All workspaces (application-wide)	One workspace only
Typical use	Reusable scripts, agents, skills	Binary-specific reference files, notes, operator outputs
Appears in Library sidebar	Yes	No — appears in Sidekick Resources
Exported with workspace	No — Library items are application-wide and are not part of workspace exports	Yes, via the Indexes, code maps, and repositories checkbox

Opening Workspace Repositories

Open Sidekick Resources and select a repository. See Browsing Workspace Resources for an overview of the sidebar's browse list and detail layout.

Each entry in the browse list shows the repository name, its file count, and its revision count.

Managing repositories

From the browse-list context menu or the hamburger menu, you can:

• Rename a repository (the hamburger menu labels this Rename Resource). In the single-pane layout you can also edit the title at the top of the detail view.
• Delete a repository and all of its stored data (the hamburger menu labels this Delete Resource). You are asked to confirm before deletion proceeds.

Show in Finder / Explorer / File Manager is available from the browse-list context menu (it opens the repository's on-disk working copy) and from a file's context menu in the detail view (it reveals that file).

The detail view lets you edit files, add new files, commit changes, and browse revision history, using the same workflow as Library items (see Editing and versioning items above).

Note

The Agent, Skill, and Operator file-type options are not available in the repository detail view. Workspace repositories support Empty File and Python Script additions only.

When to use workspace repositories

Use a workspace repository when you want to store files that are specific to a binary or project and should travel with the workspace rather than becoming part of the global Library. Examples include reference documents, analyst notes, intermediate data files produced by scripts, or any other workspace-specific content you want to version and revisit.

For content you want to reuse across multiple projects, create a Library item instead.

Workspace repositories are included in exports when you check Indexes, code maps, and repositories in the Workspace Portability dialog. See Sharing Analysis Data for the full export and import workflow.