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:

Symlink Reference

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

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