Agent-Skills.md

Agent Skills: Tool Configurations

Tool configurations for IDEs, MCP integrations, and development tools. Use when configuring IDE settings, MCP tools, or pytest. Covers conditional tool activation, configuration hierarchy, and synchronization patterns.

UncategorizedID: tianjianjiang/smith/smith-tools

Repository

tianjianjiang/smith
tianjianjiang

Install this agent skill to your local

pnpm dlx add-skill https://github.com/tianjianjiang/smith/tree/HEAD/smith-tools

Skill Files

Browse the full folder contents for smith-tools.

Download Skill

Loading file tree…

smith-tools/SKILL.md

Skill Metadata

Name
smith-tools
Description
Tool configurations for IDEs, MCP integrations, and development tools. Use when configuring IDE settings, MCP tools, or pytest. Covers conditional tool activation, configuration hierarchy, and synchronization patterns.

Tool Configurations

Scope: Configuration standards for development tools, IDEs, and MCP integrations Load if: Writing/editing IDE config files (.vscode/, .kiro/, .cursor/) OR configuring MCP tools Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md

CRITICAL: Tool Configuration

  • Check codebase and local docs BEFORE using MCP tools
  • Use MCP tools only when task specifically requires them
  • Activate tools conditionally, not by default
  • Mandate Serena MCP only for multi-session plans, not all plans
  • Require Context7 only for unfamiliar external libraries, not all libraries

This document defines configuration standards for development tools, IDEs, and external integrations.

IDE & Extension Settings

  • Global Settings: $HOME/Library/Application Support/[Code|Cursor|Kiro]/User/settings.json
  • Workspace Settings: .vscode/settings.json, .cursor/settings.json, .kiro/settings/
  • Claude Code: Same configuration across all IDEs, follow skill standards
  • Consistency: Synchronized extension preferences across all environments

Pytest Configuration (MANDATORY)

  • Log Level: log_cli_level = "WARNING" in both pytest.ini and pyproject.toml
  • Purpose: Suppress INFO/DEBUG logs from external libraries during test execution
  • Exception: Use DEBUG level only when actively debugging specific issues

For detailed pytest execution patterns: See @smith-python/SKILL.md#before-you-finish

MCP Tool Integration (Optional)

MCP (Model Context Protocol) tools provide enhanced capabilities for specific scenarios. Use them conditionally when their specific functionality is needed.

These tools are NOT required for standard development work.

Available MCP Tools

Serena MCP - Session Persistence:

  • Purpose: Persist plans and context across sessions
  • Use for: Complex multi-session tasks, plan recovery, session restarts
  • Configuration: .kiro/settings/mcp.json or IDE settings
  • Avoid: Single-session tasks, simple bug fixes

Context7 - External Library Documentation:

  • Purpose: Fetch documentation for external libraries
  • Use for: Unfamiliar NPM/PyPI packages, external API references
  • Configuration: MCP settings
  • Avoid: Libraries already in codebase, standard library usage

Fetch/WebFetch - Web Content Retrieval:

  • Purpose: Retrieve web content from URLs
  • Use for: User-provided URLs, web documentation explicitly requested
  • Configuration: Use WebFetch tool if available
  • Avoid: Content available locally, speculative browsing
  • Guardrails (WebFetch behavior):
    • Cross-host redirects are not auto-followed — WebFetch returns the redirect URL; re-call with it if the new host is trusted
    • Results are cached ~15 min per URL — a stale page can be returned within that window; expect it when re-fetching after a change
    • A server-side domain blocklist + (for the API tool) allowed_domains/blocked_domains can return nothing for blocked hosts
    • JS-heavy / SPA pages can return empty or partial content (plain HTTP fetch, no headless browser) — fall back to a browser MCP (@smith-browser_mcp/SKILL.md) for those

Browser MCP plugins (chrome-devtools-mcp, @playwright/mcp):

  • Purpose: Drive a real browser via Chrome DevTools Protocol
  • Configuration: Browser-channel choice is constrained — default to Chrome for Testing for chrome-devtools-mcp; bundled Chromium for Playwright MCP
  • Avoid: --executablePath pointing at Vivaldi / Edge / consumer Chrome — see @smith-browser_mcp/SKILL.md

For MCP server configuration in Kiro: See @smith-ctx-kiro/SKILL.md#critical-serena-mcp-is-mandatory

MCP Server Lifecycle

Installation:

claude mcp add --transport stdio --scope user server-name -- command args

Option ordering matters: all flags (--transport, --env, --scope, --header) must come before the server name; -- (double dash) separates the server name from the command + args passed to the server. Wrong ordering causes flag conflicts.

Scopes (set via --scope):

  • local (default) — current project, just you (was project in older versions); written to ~/.claude.json per-project section
  • project — shared with team via .mcp.json at repo root
  • user — across all your projects (was global in older versions); written to ~/.claude.json top-level

Transports in .mcp.json / claude mcp add-json:

  • stdio — local process spawned by Claude Code; ideal for tools needing direct system access
  • http (alias streamable-http) — remote HTTP server
  • sse — Server-Sent Events; deprecated, prefer http

Discovery + management:

claude mcp list
claude mcp get «name»
claude mcp remove «name»

In-session: /mcp shows tool count per server, flags servers advertising the tools capability but exposing none, and authenticates remote OAuth 2.0 servers.

Env vars affecting MCP runtime:

  • MCP_TIMEOUT=10000 claude — raise startup timeout (default low; bump for slow servers)
  • MAX_MCP_OUTPUT_TOKENS=50000 — raise per-tool-call output cap (default warns at 10k)

Path variables in server config:

  • ${CLAUDE_PROJECT_DIR} — project root. Claude Code substitutes ${VAR} (and ${VAR:-default}) in .mcp.json command/args before spawning the server. BUT CLAUDE_PROJECT_DIR itself is set only in the spawned server's process env, not in Claude Code's own env — so in user/project .mcp.json reference it with a fallback default like ${CLAUDE_PROJECT_DIR:-.}. Plugin-provided MCP configs substitute it directly (no default needed).
  • ${CLAUDE_PLUGIN_ROOT} — plugin asset root; only available in plugin-provided MCP configs

Server-connecting waits: Claude waits for in-flight server connections before running tools that need them. With tool search enabled (default), the wait happens inside ToolSearch; otherwise (Vertex AI, custom ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false) WaitForMcpServers is used.

Debugging failures:

  • Check logs: ~/.claude/logs/mcp-*.log
  • Startup timeout → raise MCP_TIMEOUT
  • Restart: remove + re-add the server, or restart the Claude Code session
  • Config reload: restart session after edits to .mcp.json or settings (MCP server list isn't hot-reloaded)

-32000 from an MCP server: JSON-RPC reserves -32000 to -32099 for implementation-defined "Server error" (JSON-RPC 2.0 spec §5.1). It is generic — not a Claude-Code-specific code — so the number alone says only "the server raised an error," not what failed. Recover by:

  1. /mcp — inspect connection state; re-authenticate if a remote OAuth server shows disconnected
  2. Read the server's own message/data field and ~/.claude/logs/mcp-*.log for the real cause
  3. Restart the server: remove + re-add, or restart the session (config isn't hot-reloaded)
  4. If it recurs, the fault is server-side (its auth, config, data, or deployment — or an implementation bug), not Claude Code — work the server's logs/owner first, then its issue tracker if a defect is still likely

Common issues:

  • Server not found → verify command path is absolute
  • Permission denied → check executable permissions
  • Startup timeout → increase MCP_TIMEOUT
  • Option ordering → flags before server name, -- before server command

Plugin Marketplaces

A marketplace is a catalog at .claude-plugin/marketplace.json listing plugins. Anyone can host one (git repo, local path, URL); the smith-* ecosystem treats anthropics/claude-plugins-official as the canonical official marketplace.

Install a marketplace + plugin:

/plugin marketplace add «git-url-or-path»
/plugin install «plugin-name»@«marketplace-name»
/plugin marketplace update
/plugin list

marketplace.json structure:

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "..." }
  ]
}

plugin.json (per-plugin, at «plugin»/.claude-plugin/plugin.json):

{ "name": "quality-review-plugin",
  "description": "...",
  "version": "1.0.0" }
  • Version: omit to use git-commit-as-version (every push is a new version); set explicitly to control update cadence — users only pull when this field changes.
  • Plugin caching: plugins are copied to a cache dir on install. Plugin code cannot reference ../sibling paths; use symlinks if cross-plugin sharing is needed.
  • Plugin dependencies (v2.1.143+): claude plugin disable refuses if another enabled plugin depends on the target.

Plugin-provided MCP servers: declared in .mcp.json at plugin root OR inline in plugin.json under mcpServers. Start automatically when the plugin is enabled. Use ${CLAUDE_PLUGIN_ROOT} to reference plugin assets. Plugin MCP servers appear in /mcp alongside user-configured ones.

Supply-chain trust (a plugin runs code on your machine):

Installing/enabling a plugin is a trust decision equal to running its install script — it can ship hooks (shell commands), MCP/LSP servers, and bin/ executables that run locally with your privileges, and an update can change that code. Trust by tier, highest first:

  1. anthropics/* official marketplace — canonical
  2. Known org / vendor you already depend on
  3. Unknown third-party — review before enabling

Before enabling anything you did not author, read the plugin's hooks/, commands/, bin/ executables, and .mcp.json / plugin.json mcpServers — hooks and MCP servers execute on enable, not on first use. Tier 1 is Anthropic-curated so the full read is lower-stakes, but it is not a free pass: still skim the manifest and pin to an explicit version (or commit) so an update cannot silently re-grant trust. Tiers 2-3: always do the full review.

enabledPlugins in ~/.claude/settings.json controls per-user enable state:

{ "enabledPlugins": {
    "«plugin»@«marketplace»": true,
    ...
  } }

Configuration Hierarchy

  • $HOME/.smith/ - Global personal standards (symlinked to projects)
  • AGENTS.md - Project-level agent instructions
  • .vscode/, .cursor/, .kiro/settings/ - IDE-specific configs
  • MCP tool configs - Serena, Context7, etc.

Synchronization Points

  • IDE Settings: Automatically sync from master documents
  • Project Files: Reference personal standards instead of duplicating
  • Optional Tools: Configure MCP tools conditionally based on task needs
  • Tool Extensions: Apply these standards in all generated content

Update Workflow

  1. Master Update: Modify authoritative documents
  2. Automatic Sync: Run synchronization script to update all tool configurations
  3. Validation: Verify consistency across all tools and configurations
  4. Documentation: Update project-specific documentation with references

Related

  • @smith-ctx-claude/SKILL.md - Claude Code patterns
  • @smith-prompts/SKILL.md - Structured output patterns
  • @smith-python/SKILL.md - Virtual environment, pytest patterns
  • @smith-ide/SKILL.md - IDE-specific path syntax
  • @smith-browser_mcp/SKILL.md - Browser MCP plugin reliability

Before You Finish

Before using MCP tools:

  1. Check codebase and local docs first
  2. Use MCP only when local info insufficient
  3. Configure tools conditionally per task