Discover — Reuse and Publish Agents and Skills

Discover lets you inspect public Agents, Skills, Plugins, Project templates, and Workflows before bringing them into your work. Browsing a catalog entry is different from installing its files or granting it local permissions. Review the source, instructions, license, and dependencies before running anything. Browsing works without signing in. Cloning, installing, and publishing require sign-in.

Layout and search

The left menu (Open Discover navigation on narrow screens) has three groups.

"Coming soon" items cannot be selected. Document templates is the catalog of Project document kinds; Templates explains how to install them.

The search box on Home (What would you like AI to do?) searches Project templates, Agents, Skills, and Plugins together. The query stays in the URL as ?q=, so sharing or reloading that URL opens the same results. Clear search resets it. With no match, it shows "No matches yet. Try a different keyword." Each catalog page also has its own search and sort.

Without a search query, Home shows favorite-count rankings for all six kinds. Switch between All time and This week (the rolling last seven days). While signed in, save or remove entries from cards or detail pages, then open them from Saved. Counts are public; who saved an entry and each person's saved list are private. Document template votes and the Votes sort remain separate from favorites.

Creators (/discover/creators) lists people who publish Agents, Skills, and Templates, ordered by total score. View profile opens that person's published Agents, Skills, and Templates (/discover/creators/<login>).

Review and clone an Agent

1. Complete Setup, sign in, and open Discover's Agents.
2. On an Agent's detail page, read its README, Skills this Agent uses, and lineage. A parent/source relationship shows provenance; it does not certify quality or automatically deliver future changes.
3. Choose Clone. The dialog asks for the following; both start with the source Agent's name.
   • Display name: the name shown in aachat. Required, and you can change it later
   • Handle: the name used for @mentions and the CLI. It cannot be changed after cloning. Start with a letter or digit and use only letters, digits, -, and _. Your actual handle becomes <input>.<your GitHub login>
4. Choose Continue with GitHub and approve the GitHub authorization. Cloning needs both the repo and workflow permissions: it creates a private repository and also writes any GitHub Actions workflow files the source contains.
5. The source contents are copied as one commit into a private repository <login>/<handle base name> in your GitHub account and registered as your Agent. A DM Project is also created. The default Runtime is Claude (change it as described in Agents).
6. Check the Agents screen and the new GitHub repository. With your local runtime running, give a small task to a new Session to verify the clone's behavior.

In the WebUI sidebar, Discover agents (the compass icon) in the Agent chats group also searches public Agents and opens the same dialog.

You own the copy and its future commits. Updates to the source do not automatically update your copy.

When cloning fails

When the outcome is unclear, check the Agents screen and your GitHub account before retrying. If the Agent exists but is offline, fix its local runtime instead of cloning another copy.

Add a public Skill to an existing Agent

Open a Skill's detail from Discover's Skills.

• The SKILL.md tab shows the Skill's instructions
• The Files tab lists only that Skill's directory at the published (pinned) commit. Markdown is rendered, scripts are syntax-highlighted, and binaries such as images show only their name, type, and size. Markdown with extremely deep nesting is shown as plain text
• Bundled in agent lists public Agents that include the Skill

Choose Add to my agent. An eligible target is an Agent you own, with a connected runtime and an Agent repository. With one eligible Agent the action opens that Agent's conversation directly; with several, select one. If you are not signed in or have no eligible Agent, View Skill on GitHub is shown instead. The dialog for choosing among several Agents also offers Fork on GitHub instead.

The action opens an installation conversation. Review the proposed changes and explicitly approve the installation in its card. The Agent adapts the files into its own repository, checks them, commits, and pushes. Only after that does it register the catalog installation. Confirm the repository commit and use a new Session to check the Skill. A card opening or an installation count is not proof of runtime use. Skills explains installation receipts, precedence, and Skill Ledger.

Add a public Plugin to an existing Agent

Open Discover's Plugins, read the README and Inside this plugin (Skills, commands, agents, hooks, MCP servers), and choose Add to my agent. Targets and selection work as for Skills.

The action opens an installation conversation. The Agent does not re-lay-out the bundle: it reports the plan to place it as one directory at .agents/plugins/<name>/, the Skill names that collide with existing Skills, and the environment variables the MCP servers need, then stops. Review it and explicitly approve the installation in its card. The Agent places the directory, writes .aachat-plugin.lock.json with the source repository and the installed commit, checks the result, commits, and pushes. Only after that does it register the catalog installation. Confirm the repository commit and use a new Session to check the Plugin's Skills and MCP servers.

• When a Plugin Skill's name collides with an existing Skill, the existing Skill wins and the Plugin's copy is not loaded (Skills)
• Hooks stay as files but are never executed in a Session
• Updates to the source are not applied automatically. Installed Plugins are listed on the Agent profile's Plugins tab, which marks those with a newer version. Updating and removing both start as a conversation from the row

Plugin MCP servers

A Plugin's MCP servers are read from mcp.json or .mcp.json in the Plugin and passed to the Runtime at Session start.

Header values can reference Session environment variables as ${VAR}. Keep secrets such as API keys out of the repository and provide them as the Agent's environment following Environment.

In the following cases only that server is left out and the Session continues. The omission is recorded only in the runtime log; no message appears in the UI or to the agent.

• websocket or an unknown type
• A referenced environment variable is missing
• An invalid url or headers
• The Runtime in use does not support that transport

If a Plugin's MCP server does not appear in a Session, check the conditions above and whether the required environment variables exist in the Session environment.

Start from a Project template

Project templates start a Project with its Agents already in place. Start project asks for the Team, the Project name, and the first request. The Agents the template specifies are prepared in private repositories in your GitHub account, and the first request is sent to the Lead. See Templates for conditions, interruption and resumption, and creating and publishing your own templates.

Import a Workflow into a Project

Open Workflows in Discover and review the steps, files, and required roles. Choose Add to project, select a Team and Project, enter a Workflow slug, and bind each role to a non-dormant Agent assigned to that Project as a collaborator or admin. You must also be an active collaborator or admin in the Project. Offline Agents remain eligible. Slugs start with a lowercase letter and contain up to 64 lowercase letters, digits or hyphens. The imported copy is immediately runnable. If the slug already exists, choose another one.

Prepare a publication from publication management

Choose Publish something new in Publication management, select Agent, Skill, Plugin, Project template, Workflow, or Document template and its source, then select Prepare for publication. Keep aachat running on your computer. If it is offline, ask the Desktop guide to start aachat, or run aachat up in a terminal. Then select Check connection and confirm that the status shows Connected.

Agent and Plugin sources include ordinary Agents with a GitHub repository; built-in orchestration Agents and Agents whose repository is not ready are omitted. Before preparing an Agent export, the CLI checks GitHub CLI (gh) availability and login on the runtime computer. The login must match the publication destination owner. With the current CLI, an export supports up to 4,000 files and 32 MiB of total text, with a 2 MiB limit per file. Anything accepted by export can be reviewed and published without a smaller review limit. Review storage counts identical content once and allows up to 64 MiB of unique source and public text together for rewritten files. Kind-specific limits still apply: Workflow bundles allow 128 files / 4 MiB, Plugin registration 128 files / 4 MiB, template manifests 2 MiB, and document kinds.yaml 256 KiB. Older 5.9.x CLIs retain the legacy review limits of 128 files / 2 MiB of combined source and public text. If validation fails during export or reporting, the screen shows the specific reason. Fix the indicated issue, then retry or send instructions in the conversation on the same screen.

If a Skill is missing, choose Refresh Skill list, select its source Agent, and authorize GitHub to load the list.

Your publication preparation Agent uses the Runtime on your computer to read the source and prepare a public copy. The screen shows its activity and elapsed time. When preparation finishes, it shows the file list, with markers for files kept, changed, added, or excluded. For other publication kinds, unchanged files start collapsed; open a file to load its contents and compare the original with the public version. Summaries load the definitions they need automatically. Excluded files show only their path and reason: their contents are neither uploaded for review nor published.

For Plugins, select a Skill, Agent, Command, Hook, MCP server, or other file to read its public content beside the component list. Original and reasons and Excluded files open on demand. Public file counts are separate from component counts: one configuration file can define several hooks or MCP servers. Discover preview shows the listing, README, and contents from the same draft. The preview refreshes after preparation finishes; it does not publish or install the Plugin.

Request changes in the conversation on the same screen. The Runtime edits the files and returns the updated contents for review. Drafts are saved: reopen the same URL to continue. The original Agent or Project files stay unchanged.

Select Publish this content to publish the reviewed version. Agent and Skill publications reuse one GitHub repository per source; Plugin publications reuse one per published bundle. Each subsequent publication adds the reviewed files as one new commit and updates the same Discover listing. Files removed from the reviewed content disappear from the latest tree, but remain in previously published commits. If the publication repository changed after review, publication stops; prepare and review against its latest version.

Agent publications are registered under the source Agent and reuse its existing public repository. The first publication uses the source repository name with a -public suffix. A standalone Skill starts with <source-repo-name>-skill-<skill-directory-name>-public. Previously published sources retain their existing destination. A Plugin's destination comes from the name in the bundle's plugin.json: <source-repo-name>-plugin-<name>-public. Publishing again with the same name updates that destination, and a bundle with a different name gets its own destination, so one Agent can publish several Plugins. The private source repository stays unchanged and no separate publication Agent is created. Project templates publish the reviewed documents, Workflows, and Agent configuration. A preparation conversation alone does not authorize publication. If publication fails, retry from the same screen.

For a Document template, choose a Project that defines document kinds and in which you are an Admin or Collaborator. Preparation exports that Project's kind definition as kinds.yaml; you review that one prepared file and publish it. No GitHub repository is created; the reviewed content is listed under Discover's Document templates. Publishing again from the same Project updates the same template. Publish as Template under Kind Definition in Project Settings is a separate entry point that lists a saved definition directly (Templates).

Workflows are published only through this publication manager. The reviewed snapshot is stored on the server without a GitHub repository; its publication slug remains editable during preparation. Select a published Project Workflow and review its portable files, with each step’s execution Agent replaced by a role. Paths and prose start as the original editable copy. Before review, the preparation Agent removes author-specific names, updates renamed file references and converts Agent commands into portable steps or instructions. Import binds only the step’s execution Agent; reviewed paths and prose are preserved. Run history, Project documents, connections, and secrets are not included. Steps that call a child Workflow are not supported.

Publish a Plugin

In the preparation screen in Publication management, select Plugin and the source Agent. The manager prepares a bundle from its Skills and MCP configuration. Remove anything you do not want through the conversation. プラグインとして公開 (publish as a plugin) in an Agent profile still starts the existing preparation conversation with that Agent. Both paths keep the source repository private.

The publication checkout is a sibling directory of the source repository, laid out in the Agent Plugins v1.0.0 shape: plugin.json at the root, skills/<name>/SKILL.md, an optional mcp.json, plus README.md and LICENSE. A new publication repository is created with git init from an empty directory, never from the source Agent's .git or clone history. Environment variables an MCP server needs are named, never filled in.

Review the destination, files, listing name, and description before publishing. The conversation started from an Agent profile asks you to review the Japanese and English listing texts in its confirmation card.

From the CLI, run this with the reviewed publication checkout committed. The destination is <your-GitHub-login>/<directory-name>.

cd ~/public-plugins/receipt-tools
aachat plugin publish . --agent researcher
# Review the prepared private repository on GitHub before publishing.
aachat plugin publish . --agent researcher --go-public \
  --headline-ja "領収書の取り込みを丸ごと。" --headline-en "Receipt import in one bundle." \
  --description-ja "スキルとMCPサーバーをまとめて配ります。" --description-en "Ships the skill and the MCP server together."

The first command pushes the prepared content to a missing or empty private destination. The later, explicit --go-public makes the prepared repository public and registers it on Discover; registration needs --go-public even when the destination is already public. Open the Plugin from the Publication management list to re-sync or stop its listing. A sync only re-reads the repository and never overwrites the texts written at publish time.

Publish a Skill without publishing its Agent

In the preparation screen in Publication management, select Skill and a Skill owned by one of your Agents. Team, platform, and Plugin Skills are not offered. The manager prepares only the selected Skill and supporting files in a separate publication repository. Publish on an Agent profile's Skills tab still starts the existing preparation conversation with that Agent. The source repository stays private.

Create a new publication repository with git init in an empty directory. Do not carry over the source Agent's .git directory or clone history: deleting private files in a later commit leaves their earlier content in history. Before reusing a publication repository, inspect all history, branches, and tags. If private history is present, prepare a different, empty repository.

Review the destination, files, listing name, and description before publishing. A Skill publication does not need an Agent publication profile or .aachat/public.yaml. See Skills for the required metadata and directory structure. The source Agent does not need a Discover listing or a public repository.

From the CLI, run these commands in the reviewed, committed Skill publication repository. Its directory name determines the destination <your-GitHub-login>/<directory-name>.

cd ~/public-skills/source-review
aachat skill publish .agents/skills/source-review --agent researcher
# Review the prepared private repository on GitHub before publishing.
aachat skill publish .agents/skills/source-review --agent researcher --go-public

The first command pushes the prepared content to a missing or empty private destination. A later explicit --go-public makes the prepared repository public and registers only the selected Skill in Discover. Standalone Skills require --go-public even when the destination is already public; preparation without the flag does not restore a stopped listing. Later local edits are not pushed automatically to an existing repository; commit and push corrections first. Publication stops if the destination's default branch differs from the inspected local HEAD. If registration fails after GitHub visibility changes, the repository may already be public. Check the destination, resolve the reported problem, and retry registration.

Prepare an Agent for publication

Publication exposes a separate reviewed public tree. In the preparation screen in Publication management, select Agent and the source Agent, then review identity.md, Skills, other files, and the public profile. The owner must explicitly authorize publication. 公開する (publish) on an Agent profile still starts the existing preparation conversation with that Agent.

The public profile comes from the listing approved by the human in the review screen. The name is 1–200 characters and shared across languages (title_ja equals title_en); descriptions are localized. Optional tags allow up to 3 unique keys from aachat tag list matching ^[a-z0-9][a-z0-9-]{0,31}$. The initial proposed name uses the source public.yaml name when present, otherwise the Agent display name (or its base name). The human can choose another name. No .aachat/public.yaml creation or editing is required. An existing file is ordinary publication content. Lineage comes from the clone source recorded by the server.

Review the existing identity.md, README.md, Skills, and other files needed to use the Agent. Bundled Skills can be published without frontmatter or localized listing metadata. Incomplete or malformed Skill metadata leaves that Skill out of the Skill catalog. Standalone Skill publication still requires the metadata described in Skills. Symlinks and submodules are automatically omitted with specific reasons; the output tree contains no links.

If registration fails after a push, preparation can reuse a destination recorded as this Agent's approved push. Before registration has succeeded, reuse requires the current remote HEAD to match that recorded commit.

Review every file and the Git history that will become public. Remove private memory, client information, credentials, internal paths, and material you cannot redistribute. The CLI's credential scan is a safeguard, not a complete privacy review. Marking a Skill unlisted does not hide its files in a public repository.

Publish from the CLI

These are human-owner operations using aachat and GitHub authentication. Replace researcher with your own Agent's base name. Run them from the prepared public repository, whose directory name determines the destination <your-GitHub-login>/<directory-name>; do not run them from the private working Agent repo by mistake.

cd ~/public-agents/research-companion
git status --short
# Review and commit the prepared public files before continuing.
aachat publish researcher

The tree must have a commit and no uncommitted changes. A missing or empty private destination is created/prepared and pushed privately, even if --go-public was supplied on this first call. Check the resulting GitHub repository and its contents. When the destination already exists privately, the command without the flag keeps it private and does not push your later edits. Commit and push any later corrections to the prepared destination before publication.

Only when you intend to expose that reviewed repository, run:

aachat publish researcher --go-public --name "Research Companion" --description "Reviews public sources." --tag research

Pass the reviewed profile with --name, --description, and repeatable --tag. When omitted on first registration, it uses a valid existing public.yaml, otherwise the Agent display name and description. Re-registering the same Agent and repository without profile fields preserves the reviewed public name, descriptions, and tags. Re-registration and sync refresh the commit, stars, and bundled Skills.

For an existing private destination, this changes GitHub visibility and registers the Agent in Discover. An already-public destination is registered without needing the flag. Registration reads the public repository's default-branch commit; it is not an automatic push of local edits. Check the reported repository URL and commit, then inspect the Agent and listed Skills in Discover.

If registration fails after visibility changes, check GitHub first: the repository may already be public. Fix the reported metadata or ownership problem and register again. Do not assume a registration error rolled back publication. Only a human owner can register a repository owned by that owner's GitHub account.

After successful publication or sync, a missing GitHub profile is fetched in the background. A slow or failed profile fetch does not block publication or sync. You can retry with Fetch GitHub Profile in your personal settings. Existing profile visibility is preserved; newly fetched profiles are hidden from teammates by default.

Update, sync, and stop listing

The Publication management list combines Agents, Skills, Plugins, Project templates, Workflows, and Document templates. Search by name or filter by type, then open a row to manage that publication. Listing and template draft states appear in the list. A row for a publication still in preparation returns you to the same preparation screen. Workflow and Document template rows open their public pages. Unlist removes it from Discover; copies already imported keep working.

Skill management includes SKILL.md and supporting files. Plugin management includes its README and component files. Unlisted Agents, Skills, Plugins, Workflows, and document templates remain in the list as Listing stopped. Skill and Plugin contents must then be viewed on GitHub.

For a published Agent:

• Edit display information: prepares, in a conversation with the source Agent, an update to display information such as the public name, description, tags, and Skill metadata
• Update public edition: prepares, in a conversation with the source Agent, candidates for bringing changes made in the source Agent into the public edition. Both stop after showing candidates and target files; the public repository is edited, pushed, and synced only after a person confirms
• Sync: after committing and pushing changes in the public repository, reads the public commit into the catalog. Check the synchronized content and revision

Your private source Agent and its public copy are separate. Sync does not copy private changes into the public repo or import public improvements back into the private Agent.

Each standalone Skill can be synchronized or removed individually. The CLI commands are:

aachat skill sync <skill-catalog-id>
aachat skill unpublish <skill-catalog-id>

Stop Discover listing removes the selection from Discover lists, detail pages, and new installs. Votes, comments, and install counts are kept, and publishing the same source again shows the same listing again. For an Agent, its bundled Skills are hidden too. Skills published separately from that Agent are unaffected. For a standalone Skill, only that Skill is affected. For document templates published through the existing CLI or document-kind form, the original owner can explicitly publish the same slug again to restore the original ID and ratings. Updating content alone does not relist it. The action does not delete the GitHub repository, make it private, or remove copies people already cloned. If you also need to change GitHub visibility, do that separately on GitHub. Catalog removal is not a way to retract an exposed secret; revoke the exposed credential at its provider.

Management actions are restricted to the publication owner. Do not confuse your publication management page with site-wide catalog administration.

Bring in PRs sent to the public repository

Selecting Open PRs in a published Agent's public metrics lists the open Pull Requests on the public repository as Improvement suggestions. Select the ones you want and choose one of:

• Improve source Agent: organizes candidates for bringing the selected changes into your private source Agent. It does not copy them verbatim; it proposes changes that fit the source Agent and stops
• Bring into public edition: organizes candidates for changing only the public edition. The source Agent is not changed

In both, the Agent shows candidates in a conversation and stops; changes happen only after an explicit human confirmation.

Propose an improvement to a public Agent or Skill (Pull Request)

Propose an improvement on someone else's public Agent or Skill detail has your own Agent prepare a change to that public repository.

1. Choose Propose an improvement and pick one of your Agents with a connected runtime. With one eligible Agent, its conversation opens directly. If you are not signed in or have no eligible Agent, a GitHub fork path is shown instead
2. The Agent reads the public repository as external input, shows the candidate changes for a fork or working branch and the target files, and stops
3. The Agent creates a Pull Request only after you review and choose PRを作成 (create PR) in the card

Send improvements from a cloned Agent back to its source (Issue)

On a cloned Agent's profile, クローン元に改善提案 (propose to the clone source) starts preparing a proposal in the DM. The Agent organizes the differences between the source and the identity, instructions, and Skills you changed after cloning, and saves the proposal as a Draft. Saving does not send it.

1. The human owner reads the complete draft, its evidence, and the target repository
2. Choose クローン元に送る (send to the source) and complete GitHub authorization. The public_repo or repo permission is required
3. A GitHub Issue is created in the source repository. It does not create a PR or apply code to either Agent

After submission, check the state and Issue URL in the card in the Agent's conversation. If the draft changes after review, review its latest content again. If an uncertain GitHub response leaves the submission unfinished, inspect the source repository before trying again; do not assume no Issue was created.

The owner of a published Agent sees proposals from people who cloned it on the profile's Improvement proposals tab. Review with Agent has the Agent read the Issue, compare it with its current identity, instructions, and Skills, and explain with evidence whether each point is already present, conflicts, or can be adopted. Replying to or closing the Issue happens only when the owner asks.

Related pages

• Agents: handles and display names, the Agents screen, repo delivery, and Runtime defaults
• Skills: precedence, install receipts, publication metadata, and observed usage
• Templates: starting, creating, and publishing Project templates; document kinds
• Environment: declarations and local secret approval

Categories are shared across all listing kinds. Run aachat tag list (or aachat tag list --json) and choose 1–3 keys for the work it supports. If none fits exactly, choose the closest existing category and propose an addition to the operator. Unknown or retired keys are rejected on publication.