--- sidebar_position: 6 --- # Agents Single-file `.md` resources managed alongside skills — same sync, audit, and lifecycle, different shape. :::tip When does this matter? Some AI CLIs (Claude Code, Cursor, OpenCode, Augment, Copilot CLI, Droid) distinguish between **skills** (directories with `SKILL.md`) and **agents** (standalone `.md` files). If your targets support agents, skillshare can manage both from a single source of truth. ::: ## Skills vs Agents | | Skill | Agent | |---|---|---| | **Shape** | Directory containing `SKILL.md` + optional files | Single `.md` file | | **Name resolution** | `SKILL.md` frontmatter `name` field | Filename (e.g. `tutor.md` = "tutor"), optional frontmatter `name` override | | **Source directory** | `~/.config/skillshare/skills/` | `~/.config/skillshare/agents/` (customizable via `agents_source`) | | **Project source** | `.skillshare/skills/` | `.skillshare/agents/` | | **Ignore file** | `.skillignore` | `.agentignore` | | **Sync unit** | Directory symlink (merge), whole-dir symlink (symlink), directory copy (copy) | File symlink (merge), whole-dir symlink (symlink), file copy (copy) | | **Nested support** | `path/to/skill` flattens to `path__to__skill` | `dir/file.md` flattens to `dir__file.md` | | **Tracking** | Supported | Supported | | **Audit** | Supported | Supported | | **Collect** | Supported | Supported | --- ## Directory Structure ### Global ``` ~/.config/skillshare/ ├── skills/ # Skill source (directories) │ ├── my-skill/ │ │ └── SKILL.md │ └── .skillignore ├── agents/ # Agent source (files) │ ├── tutor.md │ ├── reviewer.md │ └── .agentignore └── config.yaml ``` ### Project ``` .skillshare/ ├── skills/ │ └── api-conventions/ │ └── SKILL.md ├── agents/ │ ├── onboarding.md │ └── .agentignore └── config.yaml ``` ### Custom Source Directory In global mode, the agent source defaults to `~/.config/skillshare/agents/`. To use a custom location, set `agents_source` in `config.yaml`: ```yaml agents_source: ~/my-agents ``` Project mode always uses `.skillshare/agents/` and does not support `agents_source`. See [Configuration — agents_source](/docs/reference/targets/configuration#agents-source) for details. --- ## Agent File Format {#agent-file-format} An agent is a plain `.md` file. Frontmatter is optional: ```markdown --- name: math-tutor description: Helps with math problems step by step targets: [claude, cursor] # optional — only sync to these targets --- # Math Tutor You are a patient math tutor. Walk through problems step by step. ``` **Per-agent targets:** the optional `targets` list restricts an agent to the listed targets (aliases such as `claude-code` match `claude`). Omit it to sync everywhere. Other frontmatter fields are passed through verbatim — skillshare does not translate them between tools unless the target uses an [extension](#extensions), so an agent written for one harness may not be understood by another. Use `targets` to keep a per-harness variant of the same agent side by side (for example `reviewer.md` with `targets: [claude]` and `reviewer-opencode.md` with `targets: [opencode]`). **Naming rules:** - Filename determines the agent name: `tutor.md` = "tutor" - Optional `name` field in YAML frontmatter overrides the filename - Filenames must start with a letter or number, containing only `a-z`, `A-Z`, `0-9`, `_`, `-`, `.` - Maximum name length: 128 characters **Conventional excludes** — these filenames are always skipped during discovery: `README.md`, `CHANGELOG.md`, `LICENSE.md`, `HISTORY.md`, `SECURITY.md`, `SKILL.md` --- ## Supported Targets {#supported-targets} Only targets with an `agents` path definition receive agent syncs. Currently: | Target | Global agents path | Project agents path | |--------|-------------------|---------------------| | `claude` | `~/.claude/agents` | `.claude/agents` | | `cursor` | `~/.cursor/agents` | `.cursor/agents` | | `opencode` | `~/.config/opencode/agents` | `.opencode/agents` | | `augment` | `~/.augment/agents` | `.augment/agents` | | `copilot` | `~/.copilot/agents` | `.github/agents` | | `droid` | `~/.factory/droids` | `.factory/droids` | Targets without an `agents` entry (the majority) only receive skills. --- ## Sync Behavior Agent sync supports all three modes, same as skills: | Mode | Behavior | |------|----------| | **merge** (default) | Per-file symlinks. Local agent files in the target are preserved. On Windows without Developer Mode, agents are copied instead and kept updated and pruned like links ([details](/docs/troubleshooting/windows#file-links-need-windows-developer-mode-copying-instead)). | | **symlink** | Entire agents directory symlinked. | | **copy** | Agent files copied as real files. | ```bash # Sync everything (skills + agents) skillshare sync # Sync agents only skillshare sync agents ``` Orphan cleanup works the same way — broken symlinks or copied files that no longer have a source are pruned automatically. ### Converting agents with an extension {#extensions} Tools don't agree on agent frontmatter, and some don't read Markdown at all. Set `extension` on a target's `agents` block to run each agent through a transform script during sync: ```yaml targets: opencode: agents: extension: opencode-agents # implies mode: copy codex: skills: path: ~/.codex/skills agents: path: ~/.codex/agents extension: codex-agents # tutor.md → tutor.toml ``` - `extension` implies `copy` mode. Setting `mode: merge` or `mode: symlink` alongside it is an error. - Extensions are the same ones extras use: a bare name resolves under `~/.config/skillshare/extensions/` (`.skillshare/extensions/` in project mode), a path is used directly. See [Extension transforms](/docs/reference/commands/extras#extension-transforms) for the script contract. - When an extension changes the file extension, orphan cleanup follows the new name, so a leftover `tutor.md` copy is removed once the target gets `tutor.toml`. - A failing agent is reported and not written; the other agents still sync. The web dashboard sets this from the target's **Agents** tab. **`opencode-agents`** converts Claude-style agents for [OpenCode](https://opencode.ai/docs/agents/). It keeps only the fields OpenCode documents (`description`, `mode`, `model`, `temperature`, `top_p`, `steps`, `permission`, `hidden`, `color`, `prompt`) and adds `mode: subagent` when `mode` is missing. It drops a `model` that isn't in `provider/model-id` form, and fails when `description` is missing. An agent that sets Claude's `tools:`, `disallowedTools:`, or `permissionMode:` fails instead of being guessed at: write an OpenCode variant with `permission:` and `targets: [opencode]`. --- ## Collect Behavior Agent collect uses the same CLI contract as skill collect, but operates on `.md` agent files: ```bash # Global skillshare collect agents claude skillshare collect agents --all skillshare collect agents claude --dry-run skillshare collect agents claude --json # Project skillshare collect -p agents claude skillshare collect -p agents --all skillshare collect -p agents --json ``` Rules: - Existing source agents are skipped by default - Use `--force` to overwrite existing source agents - `--json` implies `--force` and skips the confirmation prompt - Targets with an agent [extension](#extensions) hold converted files, so they are never collected: `--all` skips them and naming one is an error --- ## `.agentignore` Works identically to `.skillignore` — gitignore-style patterns to exclude agents from sync. | Scope | Path | |-------|------| | Global | `~/.config/skillshare/agents/.agentignore` | | Project | `.skillshare/agents/.agentignore` | Example: ```gitignore # Disable draft agents draft-* # Disable a specific agent experimental-reviewer ``` Use `enable`/`disable` with `--kind agent` to manage entries: ```bash skillshare disable --kind agent draft-reviewer skillshare enable --kind agent draft-reviewer ``` --- ## Installing Agents from Repos When installing a repository, skillshare auto-detects agents: 1. Finds an `agents/` convention directory in the repo — `.md` files inside (excluding conventional excludes) are agent candidates 2. If the repo has both `skills/` and `agents/`, both are installed 3. If the repo has only `agents/` (no `SKILL.md` markers), agents are installed 4. If the repo has no `skills/`, no `agents/` dir, but has loose `.md` files at root — treated as agents (pure agent repo) ### Explicit flags ```bash # Install only agents from a repo skillshare install github.com/user/repo --kind agent # Install specific agents by name (-a shorthand) skillshare install github.com/user/repo -a tutor,reviewer # Install specific skills by name (unchanged) skillshare install github.com/user/repo -s my-skill ``` --- ## CLI Commands Most commands accept a `agents` positional argument or `--kind agent` flag to scope to agents: | Command | Example | What it does | |---------|---------|--------------| | `list agents` | `skillshare list agents` | List agents in source | | `check agents` | `skillshare check agents` | Check agent integrity and update status | | `audit agents` | `skillshare audit agents` | Security scan agents | | `sync agents` | `skillshare sync agents` | Sync only agents to targets | | `collect agents` | `skillshare collect agents claude` | Collect local target agents back to source | | `update agents` | `skillshare update agents --all` | Update tracked agent repos and metadata-backed agents | | `enable --kind agent` | `skillshare enable --kind agent tutor` | Re-enable a disabled agent | | `disable --kind agent` | `skillshare disable --kind agent tutor` | Disable an agent via `.agentignore` | | `install --kind agent` | `skillshare install repo --kind agent` | Install only agents from a repo | | `install -a` | `skillshare install repo -a tutor` | Install specific agent(s) by name | Without the kind filter, commands operate on **both** skills and agents. --- ## Data Flow ```mermaid flowchart TD SRC["Agent Source
~/.config/skillshare/agents/"] DISC["AgentKind.Discover()
Scan .md files, apply .agentignore"] SYNC["SyncAgents()
merge / symlink / copy"] TGT_CLAUDE["~/.claude/agents/"] TGT_CURSOR["~/.cursor/agents/"] TGT_OC["~/.config/opencode/agents/"] PRUNE["PruneOrphanAgentLinks()
Remove stale symlinks"] SRC --> DISC DISC --> SYNC SYNC --> TGT_CLAUDE SYNC --> TGT_CURSOR SYNC --> TGT_OC SYNC --> PRUNE ``` --- ## Project Mode Agents work in project mode the same way skills do: ```bash # Initialize project (creates .skillshare/agents/ alongside .skillshare/skills/) skillshare init -p # Install agents into project skillshare install github.com/user/repo --kind agent -p # Update project agents in place skillshare update agents --all -p # Sync project agents skillshare sync -p ``` Project agent source: `.skillshare/agents/` Installed agents (tracked) are recorded in `.metadata.json` and `.gitignore` entries are created, same as tracked skills.