Configuration

workspace.yaml

The workspace configuration file defines repositories, plugins, workspace file sync, and target clients.

# Workspace file sync (optional)
workspace:
  source: ../shared-config              # Default base for relative file paths
  files:
    - AGENTS.md                         # String shorthand: same source and dest
    - source: docs/guide.md             # Object form with explicit source
      dest: GUIDE.md                    # Optional dest (defaults to basename)
    - dest: CUSTOM.md                   # File-level source override
      source: ../other-config/CUSTOM.md
    - dest: AGENTS.md                   # GitHub source
      source: owner/repo/path/AGENTS.md

repositories:
  - path: ../my-project
    source: github
    repo: myorg/my-project
    description: Main project repository
  - path: ../other-project               # Auto-discovers skills from client paths
  - path: ../framework
    skills:                               # Custom skill paths (relative to repo root)
      - plugins/my-plugin/skills
  - path: ../legacy-repo
    skills: false                         # Disable skill discovery for this repo

plugins:
  - code-review@claude-plugins-official
  - name: superpowers@obra/superpowers
    skills:                                # Allowlist: only sync these skills
      - brainstorming
      - test-driven-development
  - name: my-plugin@my-org/my-plugin
    skills:                                # Blocklist: sync all except these
      exclude:
        - verbose-logging

clients:
  - claude
  - copilot
  - cursor

Plugin Skills

Control which skills are synced per plugin using the inline skills field on plugin entries:

plugins:
  # All skills (default — no skills field needed)
  - code-review@claude-plugins-official

  # Allowlist — only sync these skills
  - name: superpowers@obra/superpowers
    skills:
      - brainstorming
      - test-driven-development

  # Blocklist — sync all except these
  - name: my-plugin@my-org/my-plugin
    skills:
      exclude:
        - verbose-logging

Format	Behavior
omitted	All skills synced
string[] (allowlist)	Only listed skills are synced
{ exclude: string[] } (blocklist)	All skills except listed ones are synced

Skills are managed via the CLI:

• allagents plugin skills remove <skill> — disable a skill
• allagents plugin skills add <skill> — enable a skill
• allagents plugin skills list — view all skills with status

Selective install also sets up the allowlist automatically:

allagents plugin install superpowers@marketplace --skill brainstorming

Note

The top-level disabledSkills and enabledSkills arrays are deprecated (v1 format). They still work as a fallback for configs that haven’t migrated, but new configs should use the inline skills field on plugin entries instead.

Workspace File Sync

The workspace section enables syncing files from external sources to your workspace root.

Field	Required	Description
source	No	Default base directory for resolving relative file paths
files	Yes	Array of files to sync

File entry formats:

Format	Example	Description
String	AGENTS.md	Source and dest are the same, resolved from workspace.source
Object with source	{source: "path/file.md"}	Dest defaults to basename
Object with dest	{dest: "file.md", source: "..."}	Explicit source and dest

Source resolution priority:

1. Explicit source on file entry → used directly
2. No source → resolved relative to workspace.source
3. No workspace.source and no explicit source → validation error

GitHub sources:

• Format: owner/repo/path/to/file.md
• Fetched fresh on every sync (always pulls latest)

Behaviors:

• Source is the single source of truth; local copies are overwritten
• Deleted local files are restored on next sync
• AGENTS.md and CLAUDE.md automatically receive WORKSPACE-RULES injection

Repository Skill Discovery

During sync, AllAgents scans workspace repositories for skills and embeds an index in the WORKSPACE-RULES section of AGENTS.md. AI agents use this index to find and load skills from repos they’re working in.

By default, skill discovery scans each repository’s client skill directories (e.g., .claude/skills/, .agents/skills/, .codex/skills/) based on which clients are configured. Symlinks and junctions are skipped.

The skills field on each repository controls discovery:

Value	Behavior
omitted or true	Auto-discover from client skill paths
string[]	Scan only these custom paths (relative to repo root)
false	Disable skill discovery for this repo

repositories:
  - path: ../my-project                  # Auto-discovers from .claude/skills/, .agents/skills/, etc.
  - path: ../framework
    skills:
      - plugins/agentv-dev/skills        # Only scan these paths
      - plugins/agentic-engineering/skills
  - path: ../legacy-repo
    skills: false                        # No skill discovery

Skills must have a SKILL.md file with YAML frontmatter containing name and description fields. The generated index uses relative paths from the workspace root so AI agents can read the full skill instructions on demand.

Duplicate Skill Resolution

When multiple repositories (or multiple client paths within the same repo) contain skills with the same name, AllAgents picks a single winner:

Priority	Rule
1st	Skills under .agents/ paths take priority
2nd	The skill with the largest file size wins
3rd	First-seen skill wins (repository order in workspace.yaml)

This differs from plugin skill deduplication, which keeps all copies and renames them for uniqueness. Repository skills are an index of pointers, so only the best source is kept.

MCP Servers

The optional top-level mcpServers field defines MCP servers managed directly by the workspace. Servers defined here are synced to all configured project-scoped MCP clients (claude, codex, vscode, copilot).

mcpServers:
  deepwiki:
    type: http
    url: https://mcp.deepwiki.com/mcp
    headers:
      Authorization: Bearer ${DEEPWIKI_TOKEN}

  gh-server:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-github'
    env:
      GH_TOKEN: ghp_xxx

  # Per-server client filter — only sync to specific clients
  claude-only:
    type: http
    url: https://mcp.example.com
    clients:
      - claude

Field	Required	Description
type	No	http or stdio (inferred from presence of url vs command if omitted)
url	http only	HTTP URL for the MCP server
headers	No	HTTP headers map (http transport only)
command	stdio only	Executable for the stdio command
args	No	Command arguments array (stdio transport only)
env	No	Environment variables map (stdio transport only)
clients	No	Subset of project-scoped clients that should receive this server. Defaults to all configured clients.

Manage these entries declaratively in workspace.yaml, or via the allagents mcp commands. Workspace-level servers override any plugin-supplied server with the same name (with a warning).

Servers AllAgents adds are tracked in .allagents/sync-state.json; pre-existing user-managed servers in client MCP configs (.mcp.json, .vscode/mcp.json, .copilot/mcp-config.json, .codex/config.toml) are never touched.

MCP Proxy

The optional mcpProxy section rewrites HTTP MCP servers to stdio via mcp-remote for clients that need it. See the MCP Proxy guide for details.

mcpProxy:
  clients:
    - claude
    - copilot
  servers:
    my-internal-api:
      proxy:
        - codex

Field	Required	Description
clients	Yes	Clients where all HTTP servers are proxied to stdio
servers	No	Per-server overrides with additional client lists
servers.<name>.proxy	Yes (per entry)	Additional clients to proxy this specific server for

Only servers with HTTP transport (url field) are transformed. Stdio servers pass through unchanged.

VSCode Configuration

The optional vscode section controls .code-workspace file generation when vscode is in the clients list.

vscode:
  output: my-project    # Output filename (without .code-workspace extension)

Field	Required	Description
output	No	Custom filename for the generated .code-workspace file. Defaults to the workspace directory name.

Template File

Place a template.code-workspace in .allagents/ to customize the generated workspace:

{
  "folders": [
    { "path": "{path:../Shared}", "name": "SharedLib" }
  ],
  "settings": { "editor.formatOnSave": true },
  "launch": { "configurations": [] },
  "extensions": { "recommendations": ["dbaeumer.vscode-eslint"] }
}

The {path:../path} placeholder syntax resolves to absolute paths using repository paths from workspace.yaml. It works in any string value within the template (folders, settings, launch configs).

User-Level workspace.yaml

When using --scope user, AllAgents stores a separate config at ~/.allagents/workspace.yaml:

plugins:
  - superpowers@obra/superpowers

This file follows the same plugins format as the project-level workspace.yaml but does not support workspace, repositories, or clients fields. User-scoped plugins sync to user-level directories (~/.claude/, ~/.codex/, etc.) and are available across all projects.

Sync state for user-scoped plugins is tracked in ~/.allagents/sync-state.json.