mcp-web-agent-docs

name	mcp-web-agent-docs
description	Review and update agent documentation and skills in `./agents/` related to MCP-Web.

Agent Documentation Maintenance

This skill provides guidance for keeping the agent documentation and skills in ./agents/ up to date.

Documentation Structure

agents/
├── AGENTS.md              # High-level overview & navigation (symlinked to root)
├── README.md              # Meta-documentation about the agents folder itself
└── skills/
    ├── mcp-web-agent-docs/  # THIS skill - meta documentation maintenance
    │   └── SKILL.md
    └── mcp-web/             # MCP-Web library usage skill
        ├── SKILL.md         # Main skill document
        ├── examples.md      # Complete code examples
        └── api-reference-*.md  # Per-package API documentation

AGENTS.md Purpose & Content Guidelines

The AGENTS.md file serves as the high-level entry point for AI agents working in this repository. It should:

DO Include:

• Project overview: Brief description of what mcp-web is (1-2 paragraphs max)
• Architecture diagram: Simple ASCII showing component relationships
• Package map: List of packages with one-line descriptions and paths
• Navigation pointers: Where to find detailed information (skills, package READMEs)
• Available skills: List of skills with their trigger conditions
• Development commands: Common pnpm commands for the monorepo
• Code standards: Brief coding conventions (TypeScript, Biome, ES modules)
• Key entry points: Main files an agent might need to find quickly

DO NOT Include:

• Detailed API documentation (belongs in mcp-web skill)
• Full code examples (belongs in mcp-web skill)
• Implementation details of specific packages
• Tutorial-style content

Target Length

AGENTS.md should be 50-100 lines - concise enough to fit in context without overwhelming.

mcp-web Skill Purpose & Content Guidelines

The mcp-web skill (agents/skills/mcp-web/) provides detailed guidance for building MCP-Web applications.

SKILL.md Should Include:

• Design philosophy and patterns
• Project structure recommendations
• The State-Schema-Tool pattern explanation
• Quick reference checklists
• Links to additional resource files

Supporting Files:

• examples.md - Complete, runnable code examples
• api-reference-*.md - Per-package API documentation:
  • api-reference-core.md - @mcp-web/core (MCPWeb class, state tools)
  • api-reference-bridge.md - @mcp-web/bridge (MCPWebBridge class)
  • api-reference-client.md - @mcp-web/client (MCP client for Claude)
  • api-reference-integrations.md - Framework integrations (Jotai, React)
  • api-reference-tools.md - Built-in tools (screenshot, DOM, Python)
  • api-reference-decompose-zod-schema.md - Schema decomposition utilities

When to Update Documentation

Update AGENTS.md When:

• A new package is added to the monorepo
• Package purposes or locations change
• New skills are created
• Development workflow changes (commands, tooling)
• Architecture changes significantly

Update mcp-web Skill When:

• API signatures change in any @mcp-web/* package
• New patterns or best practices emerge
• New framework integrations are added
• New built-in tools are added
• Design recommendations change

Update Procedure

1. Verify Current State

Before updating, read the current documentation:

agents/AGENTS.md
agents/skills/mcp-web/SKILL.md

2. Cross-Reference with Source Code

Check that documentation matches actual implementation:

• Package exports in packages/*/src/index.ts
• Class and function signatures
• Configuration options
• Type definitions in packages/types/

3. Update in Order

1. API reference files first - These are the source of truth
2. SKILL.md second - Update patterns if APIs changed
3. AGENTS.md last - Update navigation if structure changed

4. Maintain Consistency

• Keep terminology consistent across all files
• Use the same class names (MCPWeb, MCPWebBridge, not alternatives)
• Match import paths to actual package exports

Package Reference

Current packages in the monorepo:

Package	Path	Purpose
@mcp-web/core	packages/core/	Frontend library - MCPWeb class, state tools
@mcp-web/bridge	packages/bridge/	WebSocket/HTTP bridge server - MCPWebBridge class
@mcp-web/client	packages/client/	MCP client for Claude Desktop connection
@mcp-web/react	packages/integrations/react/	React hooks and components for state management
@mcp-web/types	packages/types/	Shared TypeScript types
@mcp-web/decompose-zod-schema	packages/decompose-zod-schema/	Zod schema decomposition utilities
@mcp-web/tools	packages/tools/	Reusable tool implementations

Symlink Reference

The agents/ folder is the single source of truth. These symlinks expose it:

Source	Symlink	Purpose
agents/AGENTS.md	./AGENTS.md	OpenCode, Codex, Cursor
agents/AGENTS.md	./CLAUDE.md	Claude Code
agents/AGENTS.md	.github/copilot-instructions.md	GitHub Copilot
agents/skills/	.claude/skills/	Claude Code skills
agents/skills/	.codex/skills/	Codex CLI skills

To recreate symlinks:

# From repo root
ln -sf agents/AGENTS.md AGENTS.md
ln -sf agents/AGENTS.md CLAUDE.md
ln -sf ../agents/AGENTS.md .github/copilot-instructions.md
ln -sf ../agents/skills .claude/skills
ln -sf ../agents/skills .codex/skills

Quality Checklist

Before finalizing documentation updates:

• AGENTS.md is under 100 lines
• AGENTS.md contains no detailed API docs
• All packages are listed in AGENTS.md
• All skills are listed in AGENTS.md
• mcp-web skill SKILL.md links to all API reference files
• API reference files match actual package exports
• Class names are consistent (MCPWeb, MCPWebBridge)
• Import paths are accurate
• Code examples compile/run correctly