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.

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 description, files, actions, output, and revision history.

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

New items start as Drafts.

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 new chat and inserts a library_python_run tool call so Sidekick can inspect the 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, browse-list context menu, and file-entry context menu all expose the same launch actions for the selected entry point.

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:

• edit files in tabs
• 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)
• save local edits in the working tree
• create a manual commit with Commit
• switch between the Working tree and earlier commits with the revision selector

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

The overview panel also shows recent commits for the selected item, which is useful when you want to confirm the latest saved snapshots before switching revisions.

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 current item menus also let you:

• Rename Item
• Clone Item
• Delete Item
• Show in Finder, Show in Explorer, or Show in File Manager depending on platform

If you open a repository that is not already part of the application Library, the detail view can also offer Download to Library so you can import that repository as a named Library item.

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.

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.

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
• lets Sidekick read the output and respond in the new chat
• is best when the script is part of a larger investigation

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

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 active workspace session 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:

• Python — /slug {json} schedules library_python_run in the current chat. If no chat is selected, Sidekick creates one first. Scripts without ScriptArguments can be launched as just /slug; scripts that define ScriptArguments require JSON.
• Agent — /slug message works only when the agent prompt defines a required MESSAGE variable. Other agent prompts require /slug {json}. In both cases, Sidekick launches the agent as its own dedicated chat process.
• Skill — /slug {json} injects the rendered skill into the current chat, or creates a new chat first if needed. Skills without variables can be launched as /slug. 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 explicit With Arguments... action always opens the dialog, even when saved values exist.
• 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 by defining ScriptArguments.

When a script uses ScriptArguments:

• 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

Scripts without ScriptArguments run directly and never show the arguments dialog.

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.

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

The Repositories sidebar 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 project or standalone file) 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 Repositories sidebar
Exported with workspace	Yes, via Indexes, code maps, and repositories checkbox	Yes, same checkbox

Opening the Repositories sidebar

Click the Repositories icon in the Binary Ninja sidebar panel. The sidebar uses the same two-surface layout as other Sidekick panels: a browse list on the left and a detail view on the right.

Each entry in the browse list shows the repository name, file count, revision count, and time since the last commit.

Creating and managing repositories

Use the New Item button (or the + button in the toolbar) to create a workspace repository. You are prompted for a name. Names must be unique within the workspace.

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

• Rename a repository by double-clicking its name in the list.
• Delete a repository and all of its stored data. You are asked to confirm before deletion proceeds.
• Show in Finder / Explorer / File Manager to open the repository's on-disk working copy in your file manager.

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 Repositories 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.