Agent Sandbox Registry

agent-sandbox

Decision: Skills Design Removal and MCP Docs Convergence

无中文版

.agents/notes/implemented/architecture/2026-09-29-skills-design-removal-and-mcp-docs-convergence.md

Decision: Skills Design Removal and MCP Docs Convergence

Status: implemented

Problem

An implementation audit found that the Skills documentation and parts of the MCP documentation described features that do not exist anywhere in the code:

  1. skills-system.md was a pure design draft — the Chinese and English design/skills-system.md described a abx skill CLI command, SDK Skills classes, a Skills registry, and a skills field in template specs. None of these exist: cli/main.py has no skill command group, the SDK has no skills API, agent/tools.py registers no skill tools, and template parsing (models/template.py) rejects unknown fields.
  2. Stale Skills references across docs — README, DESIGN, template-system, architecture-overview, e2b-compatibility, and architecture linked to the deleted design or listed skills as a runtime capability.
  3. MCP docs drifted from code — the MCP design docs listed 9 unimplemented P1/P2 roadmap tools, a Skills registry integration, a --skills start option, --transport http, a qoder install target, and "auto-deploy to FC" wording, none of which match cli/commands/mcp.py, agent/mcp.py, agent/mcp_http.py, or agent/tools.py.
  4. deploy artifact format mismatch — abx mcp deploy wrote a file named config.yaml whose content was produced by json.dumps (JSON body under a YAML filename), misleading both users and downstream tooling.

Decision

Remove the unimplemented Skills design entirely and converge all MCP documentation onto the audited implementation. Do not preserve future roadmap content on the user's behalf.

Skills cleanup

MCP docs convergence

deploy artifact format fix

config.yaml now contains real YAML, using the existing pyyaml dependency (already required by the cli extra and used by cli/commands/template.py):

import yaml  # provided by the cli extra, same as cli/commands/template.py

(artifact_dir / "config.yaml").write_text(
    yaml.safe_dump(fc_config, default_flow_style=False, sort_keys=False, allow_unicode=True)
)

Keys keep insertion order; nested FC settings render as block mappings.

API Design

# Behavior change (artifact only): config.yaml content is YAML, not JSON.
# Before: json.dumps(fc_config, indent=2, ensure_ascii=False)
# After:  yaml.safe_dump(fc_config, default_flow_style=False, sort_keys=False,
#                        allow_unicode=True)
# No CLI flags, tool schemas, endpoints, or env vars changed.

Alternatives considered

Dependencies

No new dependencies. pyyaml was already declared in the cli extra in pyproject.toml (and imported by cli/commands/template.py), so the YAML artifact output adds no install requirements.

Test Strategy

Acceptance criteria