Most users only need these three steps:
- Find a capability: search the Skill Atlas by task; enable Reviewed package available when you need something importable.
- Review it: open the source and confirm the license, version, connectors, permissions, and any write, paid-call, or messaging side effects.
- Try it safely: download the ZIP and
SHA256SUMSfrom the same Release, verify the archive, import the original ZIP, and use public or test data first with this read-only prompt:
Explain the capability, inputs, permissions, external side effects, and estimated cost.
Perform a read-only check only: do not call paid APIs, modify data, or send messages.
If anything is missing, list it first; do not guess or continue.
If you do not know where to begin, open Starter packs. If you only want a ready-made package, jump to Install one curated Skill in 5 minutes. If an import fails, start with Troubleshooting.
Choose the path that matches your goal:
- Use a curated Skill: download a ZIP from Releases and import it into WorkBuddy.
- Find a public Skill: search the Skill Atlas, review provenance and risk, then install it.
- Start from a task category: open the shareable category directory, then continue with the filtered Atlas search.
- Package a public Skill for WorkBuddy: follow the adaptation guide.
- Report a reviewed package problem: use the package feedback form and include the failure stage.
Not sure how to interpret a result? Use the catalog reading guide before choosing a candidate.
For a categorized list of official docs, learning material, and evaluation references, see the WorkBuddy resource map.
If you want a task-based starting point instead of a broad search, use the Starter packs list.
For manually reviewed WorkBuddy documentation, MCP integrations, workflows, and benchmarks, also browse the Awesome WorkBuddy ecosystem index. It complements this broad, metadata-first catalog; it is not a replacement for checking the exact source and license.
For a task-oriented community walkthrough, see the WorkBuddyGuide. For reproducible Agent task evaluation, see Tencent WorkBuddy Bench. Use these references alongside the exact source and license of any Skill you choose.
The catalog is a review-oriented snapshot. Its current size is published in
catalog-meta.json
under records; use it to narrow your search, then follow each result's source
link for the latest upstream version.
Choose the official installer for your computer before importing a Skill:
| Platform | Official setup |
|---|---|
| macOS 12+ | Mac Installation Guide |
| Windows 10 1809+ or Windows 11 | Windows Installation Guide |
After WorkBuddy opens and you sign in, continue with the installation path below. The official guides are the source of truth for system requirements, installers, first-launch security prompts, and permissions.
Before the first real task, keep Default Permissions enabled and use a separate, recoverable workspace. Switch to Full Access only for a trusted, isolated task after checking its impact.
| If you want to… | Do this first |
|---|---|
| Install a Skill from WorkBuddy itself | Open the built-in Skill Marketplace, inspect the author and version, then install and review its permissions. |
| Install a reviewed package now | Open curated packages, download its ZIP, verify SHA256SUMS, and upload the original ZIP in WorkBuddy. |
| Find a capability | Search the Skill Atlas, enable Reviewed package available when you need an installable result, then inspect the source and license. |
| Search from a checkout | Run python3 scripts/query_catalog.py <term> --installable --limit 10 for a ready-to-download shortlist, or add --package-status reviewed for a broader package filter. |
| Turn a public source into a package | Use the adaptation guide after reviewing the immutable source and license. |
| If your goal is… | Start with… |
|---|---|
| Add one reusable capability | Skill Marketplace — a Skill answers “what can WorkBuddy do?” |
| Assemble a role with capabilities and connectors | Expert guide or Expert Team guide — configure who performs the work |
| Reuse a finished scenario or generated result | Explore — start from an existing outcome and make your version |
This distinction prevents installing a Skill when you actually need a role configuration or a ready-made scenario.
For platform-level instructions, use the official WorkBuddy quickstart, official Skills tutorial, MCP guide, and Automation guide. For the product reading order, first see the official WorkBuddy overview; for task lists, parallel tasks, conversations, and result panels, see the official Agents quickstart. Before starting a task, use the official Task Bar guide to choose the workspace, model, installed Skills, connectors, and permission mode.
Choose the work mode to match the risk of the task:
| Need | Mode | First move |
|---|---|---|
| Ask questions or inspect information | Ask | Request a read-only answer or file inventory |
| Review a multi-step plan before execution | Plan | Ask for scope, files, side effects, and a stopping condition |
| Execute a trusted, reversible task | Craft | Start in a recoverable workspace and review the first result |
When unsure, start with Ask or Plan; the mode and permission setting are separate controls. For a monorepo or a large checkout, also follow the official large-repository guide to narrow the working scope with directory instructions, focused worktrees, and per-package configuration. For model selection, Auto Mode, provider presets, custom endpoints, or local Ollama, use the official Model Configuration guide. If an imported Skill needs a connector, use the official Connector guide to choose MCP + Skill or CLI + Skill and review authentication and permissions. You can also browse the official Skill Marketplace and Explore pages for ready-made capabilities and examples. For the Open Platform's exact ZIP layout, required frontmatter, and parser troubleshooting, see the official Open Platform Skill guide. If you plan to publish a Skill, Connector, or other ecosystem asset, start with the Open Platform overview and onboarding guide for verification, testing, review, and publishing prerequisites. This repository explains catalog discovery and packaging; the official docs remain the source of truth for product UI and platform behavior.
If you do not need a ZIP from this repository, open Skill Marketplace from the WorkBuddy sidebar. Search by capability or category, open a result to check its description, author, and version, then select Install. After installation, review the enabled Skill and its permissions before using it with real data. You can manage installed Skills from the Skills section: disable, update, or uninstall a Skill when it is no longer needed. See the official Skill Marketplace guide for the current UI and built-in security scan behavior.
| Path | Best for | Scope | Notes |
|---|---|---|---|
| WorkBuddy UI | Most users | Current workspace | Upload the original Release ZIP from Experts · Skills · Connectors → Skills. No local CLI is required. |
gh skill install |
Agent Skills-compatible hosts | The directory passed to --dir |
Use a project directory such as .workbuddy/skills for version-controlled, project-specific skills. The command is still preview. |
Local ~/.workbuddy/skills/ |
Local development and repeated experiments | User-wide | Copy only after reviewing the source; reload the host if it does not discover the new directory automatically. |
Do not mix these paths in one installation step. Pick the scope first, record the source commit or release, and use the same path when updating or removing a Skill.
Download the ZIP you need from the latest release. The reviewed package index exposes a ready-to-copy download_command; the equivalent command for oss-review is:
mkdir -p workbuddy-download
gh release download \
--repo sandbaseai/workbuddy-skill \
--pattern 'oss-review-workbuddy-skill.zip' \
--pattern SHA256SUMS \
--dir workbuddy-download \
--clobberThe --clobber flag makes the command safe to repeat when you are refreshing
an existing download directory.
Do not unzip and repackage the archive: SKILL.md is already at the archive root.
For reproducible downloads, also download SHA256SUMS from the same release and
verify an archive in the same directory:
cd workbuddy-download
sha256sum --check SHA256SUMS --ignore-missingIf sha256sum is unavailable, use the repository's cross-platform Python
helper instead. The helper also rejects an extra WorkBuddy ZIP that is absent
from SHA256SUMS:
python3 scripts/verify_release.py workbuddy-downloadWhen the repository is available locally, prefer the Python helper for the
complete package-set check; use sha256sum when you only need to verify the
selected archive.
In WorkBuddy, open Experts · Skills · Connectors → Skills → Add Skill, upload the ZIP, and finish the import. If the Skill uses a connector, enable that service in the current workspace.
If a connector is involved, complete this preflight before the first real task:
- Identify the connector's required service, account, scopes, and whether it uses MCP + Skill or CLI + Skill.
- Prefer MCP + Skill for a network API. Choose CLI + Skill only when the CLI is mature and cross-platform; the two approaches cannot be mixed in one connector.
- Authenticate through WorkBuddy's connector flow; never paste tokens or API keys into the conversation.
- Run its status or read-only operation first, and confirm the target workspace and data boundary.
- Ask the Skill to name every write, message, paid call, and external side effect before approving it.
For CLI connectors, use the connector's declared install and status steps rather than assuming a system-wide Node.js or Python installation. WorkBuddy can provide a managed runtime when the connector declares one; see the official Connector guide for the current fields and authentication flow.
Ask the Skill to explain its plan before allowing paid calls, data writes, or messages. Copy this prompt:
Explain the capability, inputs, permissions, external side effects, and estimated cost you will use.
Perform a read-only check only. Do not call paid APIs, modify data, or send messages.
If anything is missing, list what I need to confirm.
After reviewing the source, permissions, and plan, run a small task with public data. Avoid confidential data, personal data, and production systems during the first test.
- Search the Skill Atlas for a task, capability, category, or review signal such as
ocr,web search,research, orno-static-flags. If you want an installable reviewed package immediately, set WorkBuddy package → Reviewed package available before searching. - Open the source link and check the license, inputs and outputs, network access, credential requirements, and side effects.
- Prefer Skills with clear documentation, a known version, and verifiable provenance. Pin a tag or commit SHA when reproducibility matters.
- After importing, use the safe-check prompt above before running a real task.
Hosts supporting the open Agent Skills convention can preview and install from GitHub:
The command details are maintained in the official GitHub CLI gh skill manual; this command family is currently in preview.
gh skill is a host-side installer, not WorkBuddy desktop's ZIP importer. For the WorkBuddy desktop app, use the Release ZIP path above; use gh skill only when your target host explicitly supports it.
gh skill search incident --limit 10
gh skill preview owner/repository skills/path/to/skill
gh skill install owner/repository skills/path/to/skill --pin v1.2.0 --dir .workbuddy/skillsFor a host-managed destination, choose the host and scope explicitly. This also avoids silently installing an unpinned default-branch version:
gh skill preview sandbaseai/workbuddy-skill skills/oss-review
release_tag="$(gh release view --repo sandbaseai/workbuddy-skill --json tagName --jq .tagName)"
gh skill install sandbaseai/workbuddy-skill skills/oss-review \
--agent codex --scope project --pin "$release_tag"Use --scope user for a user-wide installation, or --dir for a custom
directory. Supported agents and scopes change with this preview command; check
the current install reference
before copying a command into automation.
If your host does not provide gh skill, use the source link from the Atlas and
follow the adaptation guide instead. Installation is always
an explicit step after you review the source and permissions.
Choose the same scope you used during installation:
- WorkBuddy Marketplace: open the installed Skills view to update one Skill or batch-update several. Disable a Skill before a sensitive task, and uninstall it when it is no longer needed. See the official Skills Marketplace guide.
- Release ZIP: download the replacement ZIP from the same release channel, verify its checksum, and import it through the same WorkBuddy flow. Keep the old version until a small read-only check passes if rollback matters.
- Project-scoped
gh skill: review the new source and pin, then install the replacement into the same project directory. Commit the resulting change so teammates receive the same version. - Custom
--diror user directory: remove only the exact Skill directory after checking its path; do not delete the parent directory or unrelated Skills. Reload the host and confirm that the Skill is no longer listed.
Record the source URL, commit/tag, package version, and checksum in the project when reproducibility matters. If an update changes permissions, connectors, or external side effects, repeat the safe first check before using real data.
Use “Skill name” to complete “goal”.
First provide the plan, required permissions, input data, cost, and side effects.
Start with a read-only check; do not guess arguments or run unconfirmed paid or write operations.
Cite evidence for each conclusion. If the task fails, explain the failure point,
what was tried, and the available next steps.
For asynchronous image, audio, or video jobs, preserve the returned run_id and poll the same job until it completes or fails. Do not create duplicate paid jobs while waiting.
Use the first matching row and stop after the stated next step. This avoids repeating a paid or write operation while the actual failure is still unknown.
| Symptom | First check | Next step |
|---|---|---|
| Import fails | The original Release ZIP has SKILL.md at its archive root |
Do not compress it again; re-download and verify the package |
| Tools or connectors are missing | The required service is enabled in the current workspace | Reload WorkBuddy, then run a read-only status check |
gh skill is unavailable |
The host does not provide the preview command | Open the Atlas source link and use the adaptation guide |
| No suitable Skill appears | The search term is a short capability phrase | Search related catalog entries; the catalog is discovery, not trust |
| Schema validation fails | The current capability schema and required fields | Retry once with current fields only; do not guess arguments |
| Authorization, balance, or permission error | Account, workspace, and permission mode | Check settings without pasting secrets; ask for the exact missing approval |
| Result is uncertain | Evidence, sources, and limitations in the response | Do not treat a guess as execution; request a verifiable result |
Do not delete, move, or overwrite local files, and do not run a cleanup tool before making a backup. Work through these checks in order:
- Confirm that you are signed into the original account and opened the original workspace; account isolation can hide data that is still on disk.
- Quit WorkBuddy and copy the relevant data directory or database to a separate backup location. Keep the original untouched while testing.
- Check the current behavior in the official Memory guide and the official FAQ for your version.
- If the problem followed an account switch, treat workbuddy-account-migrate as an external MIT-licensed reference: start with its diagnostic mode, inspect the source, and confirm its backup and rollback path before deciding whether to run it. It modifies local database, memory, and connector data; this repository does not run it or treat it as risk-free.
- After recovery, use a read-only task to verify conversations, memory, and connectors before any write or cleanup operation.
For more help, see Support. For security concerns, read the security policy.