---
title: "Discover — Reuse and Publish Agents and Skills"
description: "Find public capabilities, clone or install them, review publication content, and manage catalog updates and removal."
---

# Discover — Reuse and Publish Agents and Skills

[Discover](/en/discover) lets you inspect public Agents, Skills, and templates 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. For templates, use the [comparison guide](/en/docs/templates).

## Clone an Agent

1. Complete [Setup](/en/docs/setup), sign in, and open Discover → Agents.
2. Open an Agent's detail page. Read its identity, repository, available Skills, and lineage. A parent/source relationship shows provenance; it does not certify quality or automatically deliver future changes.
3. Choose **Clone**, review the name and runtime, and complete any GitHub authorization requested. The source contents are copied to a private repository in your GitHub account and registered as your Agent; a DM Project is also created.
4. Check your Agents list and the new GitHub repository. Keep your local runtime running and begin a small task in a new Session to verify the clone's behavior.

You own the copy and its future commits. Updates to the source do not automatically update your copy. If cloning fails, check GitHub authentication and repository access before retrying; inspect your Agents list and GitHub account first when the outcome is unclear. 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 Discover → Skills, read the Skill's instructions and supporting files, and choose its install action. An eligible target is an Agent you own, with a connected runtime, a team context, and an Agent repository. With one eligible Agent the action opens that Agent directly; with several, select one. Without a signed-in eligible Agent, the page offers a GitHub path instead of starting an installation.

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 should 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](/en/docs/skills) explains installation receipts, precedence, and Skill Ledger.

## Prepare an Agent for publication

Publication exposes a **separate reviewed public tree**, not a filtered view of a private repository. The owner must explicitly authorize publication. Start the publication preparation from your Agent's publication action, inspect the prepared files and public profile, and decide which Skills to list before using the publication card's final action. Agent preparation alone does not authorize making a repository public.

A public tree needs an appropriate root `README.md` for its Discover detail and clone flow, `identity.md` for the cloned Agent, and `.aachat/public.yaml` for its catalog profile. A minimal metadata file is:

```yaml
name: Research Companion
description: Reviews public sources and writes a referenced report.
tags: []
```

The name is 1–200 characters. Only `name`, `description`, `tags`, and optional `lineage` are accepted at the top level. If this is derived from another public Agent, optional lineage can identify **one** parent:

```yaml
name: Research Companion
description: Reviews public sources and writes a referenced report.
tags: []
lineage:
  parents:
    - github_repo: example/research-agent
```

Replace the example parent with the actual catalog source; omit lineage if there is no parent. Self-reference and cyclic ancestry are not valid. Skills in `.agents/skills/<name>/SKILL.md` also need the localized publication metadata shown in [Skills](/en/docs/skills).

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.

```bash
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:

```bash
aachat publish researcher --go-public
```

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.

## Update, sync, and stop listing

In your publication management page under Discover, select the publication you own. Prepare and review changes in its public repository, commit and push them, then use its sync action to read the public commit into the catalog. Check the displayed 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.

**Stop listing** removes the Agent and its published Skills from the catalog and clears the publication association. It 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.

## Send improvements back to the source

A cloned Agent can prepare an **upstream proposal Draft**. Read the complete draft, included evidence, and target repository before the human owner submits it. That submission creates a **GitHub Issue** in the upstream repository. It does not create a PR or apply code to either Agent. After submission, follow the Issue URL and proposal state in the Agent's proposal card/inbox.

If the draft changes after review, review its latest content again. If submission remains `submitting` after an uncertain GitHub response, inspect the upstream repository before attempting another submission; do not assume no Issue was created. GitHub account authorization and the required scope must be valid.

Discover also has a separate improvement conversation that prepares changes and, after an explicit human action, can create a **GitHub Pull Request**. Its publication/improvement card is a different path from the clone's upstream proposal Issue. Review the destination and action shown on the card before approving it.

## Related pages

- [Agents](/en/docs/agents): ownership, repo delivery, and runtime selection
- [Skills](/en/docs/skills): install receipts, publication metadata, and observed usage
- [Templates](/en/docs/templates): document kinds, Project starts, and client entry
- [Environment](/en/docs/environment): declarations and local secret approval