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

clients:
  - claude
  - copilot
  - cursor

# Disabled skills (optional)
disabledSkills:
  - superpowers:brainstorming
  - my-plugin:verbose-logging

Disabled Skills

The disabledSkills array lists skills that should be excluded from sync. Each entry uses the format plugin:skill where plugin is the plugin name and skill is the skill folder name.

disabledSkills:
  - superpowers:brainstorming    # Disable brainstorming from superpowers plugin
  - my-plugin:verbose-logging    # Disable verbose-logging from my-plugin

Disabled skills are managed via the CLI:

• allagents plugin skills remove <skill> - Add to disabledSkills
• allagents plugin skills add <skill> - Remove from disabledSkills
• allagents plugin skills list - View all skills with status

Enabled Skills

The enabledSkills array lists skills that should be included in sync (allowlist mode). When configured, only listed skills are synced — all others are excluded.

enabledSkills:
  - superpowers:brainstorming
  - superpowers:test-driven-development

This is populated automatically when using plugin install --skill:

allagents plugin install superpowers@marketplace --skill brainstorming

Use either disabledSkills (exclude specific skills) or enabledSkills (include specific skills), not both for the same plugin. If both are present, enabledSkills takes precedence.

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.

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.