dotagents-config-admin

name	dotagents-config-admin
description	Use this skill when you need to inspect, change, or create DotAgents configuration. It teaches the canonical .agents file layout, layer precedence, and safe edit recipes for settings, models, MCP, prompts, agents, skills, tasks, and knowledge notes.

DotAgents Config Admin

Overview

Treat the layered .agents filesystem as the canonical editable DotAgents configuration surface.

• Global layer: ~/.agents/ (default)
• Workspace layer: ${DOTAGENTS_WORKSPACE_DIR}/.agents/ when DOTAGENTS_WORKSPACE_DIR is explicitly set
• Workspace-relative shorthand: ./.agents/ when referring to the current repository workspace layer
• Workspace wins on conflicts when present
• Prefer direct file editing over narrow app-specific config tools

When changing unfamiliar DotAgents config, inspect the relevant files first, then make the smallest safe edit.

Canonical file map

Use ~/.agents/ by default. When DOTAGENTS_WORKSPACE_DIR is explicitly set, the workspace layer uses the same relative paths under ${DOTAGENTS_WORKSPACE_DIR}/.agents/ (often referred to as ./.agents/ from the workspace root).

• ~/.agents/dotagents-settings.json — general app settings
• ~/.agents/mcp.json — MCP-related config
• ~/.agents/models.json — model/provider config
• ~/.agents/system-prompt.md — system prompt override
• ~/.agents/agents.md — agent-wide guidelines
• ~/.agents/agents/<id>/agent.md — agent identity/frontmatter
• ~/.agents/agents/<id>/config.json — nested per-agent config
• ~/.agents/skills/<id>/skill.md — skill definition and instructions
• ~/.agents/tasks/<id>/task.md — repeat task definition
• ~/.agents/knowledge/<slug>/<slug>.md — durable knowledge note

Layering rules

• ~/.agents/ is the default layer for user-wide defaults
• Use ${DOTAGENTS_WORKSPACE_DIR}/.agents/ for workspace-specific behavior only when DOTAGENTS_WORKSPACE_DIR is explicitly set
• Config merge is shallow by key
• Agents, skills, tasks, and knowledge notes merge by ID
• When a workspace file intentionally overrides a global file, edit the workspace copy

Edit workflow

1. Identify the config surface the user actually wants changed
2. Inspect the existing file before editing
3. Prefer editing the canonical .agents file directly
4. Keep edits minimal and preserve surrounding structure
5. If a change is risky or ambiguous, ask the user before applying it

Recipes

Change general settings

Edit dotagents-settings.json for app-level behavior that is not MCP-, model-, or layout-specific.

Change model/provider configuration

Edit models.json for model presets, selected preset IDs, provider API keys/base URLs, and related model settings.

Change MCP configuration

Edit mcp.json for MCP server definitions and enablement-related config.

Change prompt behavior

• Edit system-prompt.md to change the core assistant prompt
• Edit agents.md to change reusable agent-wide guidance

Change an agent profile

• Edit agents/<id>/agent.md for identity, display text, role, and other frontmatter-friendly fields
• Edit agents/<id>/config.json for nested config like connection, tools, models, or skills config

Change a skill

Edit skills/<id>/skill.md. Keep the frontmatter valid and update the markdown instructions carefully.

Change a repeat task

Edit tasks/<id>/task.md. Frontmatter defines the task metadata; the markdown body is the task prompt.

Change durable knowledge

Edit knowledge/<slug>/<slug>.md directly. Use canonical frontmatter: kind: note, id, title, context, numeric millisecond createdAt/updatedAt, and comma-separated tags. Default most notes to context: search-only; reserve context: auto for a tiny curated subset.

Guardrails

• Do not invent non-canonical config paths when a canonical .agents path exists
• Avoid broad rewrites when a targeted edit is enough
• Respect process boundaries: renderer must not import from main-only files
• If both global and workspace layers exist, verify which layer should own the change before editing