feat: first-class agent support

[mk-imagine]

Feature Request

Agents should be first-class citizens in skillshare, alongside skills. Currently agents must be managed as extras, which is a generic file-sync mechanism that lacks the discovery, install, update, and lifecycle features that skills enjoy.

Motivation

AI CLI tools increasingly support custom agents (Claude Code /agents, etc.) as a primary extensibility mechanism — on par with skills/prompts. Treating agents as unstructured extras means:

• No skillshare install user/repo -a my-agent workflow
• No skillshare list --agents, check, update for agents
• No per-agent frontmatter (targets, versioning, descriptions)
• Extras sync preserves subdirectory structure, so agents organized in subdirs (e.g. agents/curriculum/, agents/software/) land in subdirs that tools like Claude Code cannot discover (see feat: flatten option for extras sync #97)
• No audit/security scanning for agent files

Proposed Design

Mirror the skills model:

skillshare install user/repo --agents          # install agents from a hub/repo
skillshare install user/repo -a my-agent       # install specific agent
skillshare list --agents                       # list installed agents
skillshare check --agents                      # check for updates
skillshare update --agents                     # update all agents
skillshare sync --agents                       # sync agents to all targets
skillshare collect --agents                    # pull agent changes back to source

Agent frontmatter (e.g. in AGENT.md or reuse skill frontmatter conventions):

---
name: curriculum-tactician
description: Execution planning agent for curriculum design
type: agent
targets: [claude]
version: 1.2.0
---

Config:

agents:
  - name: curriculum-tactician
    source: github.com/myorg/agents
    track: true

targets:
  claude:
    agents_path: ~/.claude/agents   # separate from skills_path

Relationship to #97

First-class support would also resolve the flatten issue naturally — skillshare would own the agents directory and sync files flat by default, matching how target CLIs expect to discover them.

[runkids]

Thanks for the proposal! This is being planned.

[khuongduybui]

@runkids I saw the spec you just added. Does it mean we are going to have agents and prompts supported soon?

[runkids]

Good news: yes, first-class agent support is actively in progress! The skills sub-key refactor in v0.18.3 is part of the groundwork.

Bad news: this touches a lot of existing code and architecture (install, sync, collect, update, list, TUI, Web UI, etc.), so it needs more time to get right and test thoroughly. On top of that, each AI CLI has its own conventions for agents — for example, Codex uses TOML instead of Markdown — so there's research needed to ensure skillshare handles these differences cleanly.

Will keep this issue updated as things progress. Stay tuned!

[cptspacemanspiff]

Hey, so I just ran into your project after implementing my own agent synchronization.

I was briefly looking at your agent branch, and saw that you did not handle any differences in available models between different harnesses.

(I may not understand agents fully), but it seems like one of the main issues of agents is to be able to run a specialized prompt, with potentially a different model than the base model, for instance the planning agent may be opus, and the implementation agent may be sonnet.

Then, when you shift to multiple harnesses, which have different models available you need to map between the original source models and the models available in the new harness.

IE

• Opus -> gpt5.4 or GLM5.1.
• Sonnet -> Kimi k2.5
• Haiku -> minimax M2.7

What I ended up doing (not sure if it's best) was to name the model something generic "large_reasoning" model in the source_of_truth location, and then having a mapping file in the repo, which tells each harness what that maps to. Then the sync operation, copies over the file, with touchups/needed adjustments.

There are a couple other things like that regarding specialized front-matter (color for instance, claude supports 'green' but opencode wants a hex), but I think that is the important one, maybe reasoning effort as well, though that is more of a model characteristic honestly (opus medium == GLM5.4 High).

Anyway, not sure what direction exactly you are taking this, but figured I would throw this in as a request, for how I am imagining a system like the agent-sync to work, and what I would like out of it.

[runkids]

Great point, thanks for the detailed write-up from your own implementation!

Quick thought on the model/frontmatter divergence problem: skillshare already supports per-target include/exclude for both skills and agents. So rather than centralizing a mapping file, users can maintain per-harness agent variants and route them via config, e.g.:

targets:
  claude:
    agents:
      exclude: ["*-codex"]
  codex:
    agents:
      exclude: ["*-claude"]

Then planner-claude.md (uses Opus) and planner-codex.md (uses gpt-5.4) live side by side in the source, and each target only pulls what it can run.

This sidesteps semantic translation entirely — skillshare stays a file-level sync tool, and heterogeneity is handled by the user's own naming + filter rules. It's more verbose than a mapping file, but it also means we don't have to understand every harness's model catalog or frontmatter quirks.

That said, I think your color: green → hex point is a real gap that filters can't solve. Will think about whether a lightweight frontmatter transform hook makes sense down the line. Keeping this in mind as the agent work progresses!