Skip to content

docs: enterprise onboarding guide for team skills repos #344

@christso

Description

@christso

Summary

Add a first-class guide and template for enterprises setting up a shared skills repository that distributes to all developers via AllAgents.

Motivation

Research into WiseTechGlobal/Tools.WtgCopilotSkills showed a common enterprise pattern: a central git repo containing skills and an MCP server, distributed to developer machines. Their onboarding is "clone this repo, run sync script." AllAgents can serve this use case better but lacks documentation showing the path.

Proposed Solution

1. Guide — "Setting up a team skills repo with AllAgents"

Should cover:

  • Creating a plugin repo — directory structure with skills/, .mcp.json, plugin.json (or convention-based layout)
  • Workspace config — example workspace.yaml pointing to the repo as a local plugin:
    plugins:
      - source: "../team-skills-repo"
        clients: [claude, copilot, cursor, codex]
  • Distribution — how to share the workspace config across the team (checked into each project repo, or user-level ~/.allagents/workspace.yaml)
  • Multi-repo setups — core org skills + team-specific skills as separate plugins
  • MCP server distribution — how .mcp.json in the plugin repo auto-syncs to all clients
  • Updatingallagents update pulls latest from plugin sources; for local path plugins, developers pull the repo themselves

2. Template repo

A starter template for enterprise skills repos:

  • Example skill structure (skills/<name>/SKILL.md with valid frontmatter)
  • Example MCP server config (.mcp.json)
  • Example workspace.yaml for consumers
  • GitHub Actions CI workflow running allagents skill validate (depends on feat: skill validate and fix CLI commands #345)

Acceptance Criteria

  • Guide published in docs (website or repo docs)
  • Covers the full journey: create repo → configure workspace → distribute to team → update
  • Includes concrete workspace.yaml examples for single-repo and multi-repo setups
  • Template repo created (or template directory in docs) that can be cloned as a starting point
  • Explains how local path plugins differ from GitHub URL plugins (no auto-fetch, team pulls manually)

Context

Enterprise adoption requires a clear onboarding story. Currently teams build their own distribution scripts because the AllAgents path isn't well-documented for this use case.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions