Agents

Single-file .md resources managed alongside skills — same sync, audit, and lifecycle, different shape.

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:

agents_source: ~/my-agents

Project mode always uses .skillshare/agents/ and does not support agents_source.

See Configuration — agents_source for details.

Agent File Format

An agent is a plain .md file. Frontmatter is optional:

---
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, 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

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).
symlink	Entire agents directory symlinked.
copy	Agent files copied as real files. Copies are tracked in `.skillshare-manifest.json`, so orphan cleanup removes only copies skillshare wrote and you have not edited; your own agent files in the target are preserved.

# 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

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:

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

# 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 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:

# Disable draft agents
draft-*
# Disable a specific agent
experimental-reviewer

Use enable/disable with --kind agent to manage entries:

skillshare disable --kind agent draft-reviewer
skillshare enable --kind agent draft-reviewer

Installing Agents from Repos

When installing a repository, skillshare auto-detects agents:

Finds an agents/ convention directory in the repo — .md files inside (excluding conventional excludes) are agent candidates
If the repo has both skills/ and agents/, both are installed
If the repo has only agents/ (no SKILL.md markers), agents are installed
If the repo has no skills/, no agents/ dir, but has loose .md files at root — treated as agents (pure agent repo)

Explicit flags

# 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

Project Mode

Agents work in project mode the same way skills do:

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

Skills vs Agents​

Directory Structure​

Global​

Project​

Custom Source Directory​

Agent File Format​

Supported Targets​

Sync Behavior​

Converting agents with an extension​

Collect Behavior​

.agentignore​

Installing Agents from Repos​

Explicit flags​

CLI Commands​

Data Flow​

Project Mode​