MCP

MCP Client

The runtime side that discovers capabilities, invokes tools, and can also expose Skill catalogs to the model.

Client role

An MCP client coordinates capability discovery, invocation, and result use inside an AI application or agent runtime. It decides which servers are available, what tools or resources can be called, and how returned data enters the agent workflow.

Adding Skill support

A client that supports Skills needs a lifecycle around local or provisioned Skill folders. The same pattern works whether Skills are project-level, user-level, organization-level, or built into the client.

Discover

Scan configured directories for subfolders containing SKILL.md.

Parse

Extract frontmatter metadata, validate required fields, and keep the body available for activation.

Disclose

Expose only name and description to the model as a compact catalog.

Activate

Load full instructions only when the task matches a Skill or the user explicitly selects one.

Preserve

Deduplicate activated Skills and protect their instructions from context compaction.

Mini client simulation

This small script shows the client-side decision: inspect the user request, choose whether a capability is relevant, call it with structured input, then shape the final answer.

import { searchDocs } from "./search-docs.js"

const capabilities = [
  {
    name: "search_docs",
    description: "Search MCP and Skill documentation pages.",
    call: searchDocs
  }
]

export function answerQuestion(question) {
  const shouldUseDocs = /mcp|skill|server|client|protocol/i.test(question)

  if (!shouldUseDocs) {
    return "This question does not need the docs search capability."
  }

  const tool = capabilities.find((item) => item.name === "search_docs")
  const result = tool.call({ query: question, limit: 3 })

  if (result.error) {
    return `Tool failed: ${result.error.message}`
  }

  if (result.results.length === 0) {
    return "I searched the docs but did not find a matching page."
  }

  return result.results
    .map((page) => `- ${page.title}: ${page.url}`)
    .join("\n")
}

Where clients scan

Local clients commonly scan project and user scopes. The .agents/skills/ convention improves interoperability across tools.

Scope	Example path	Purpose
Project	`<project>/.agents/skills/`	Repository-specific Skills shared by the team.
Project native	`<project>/.client/skills/`	Client-specific project Skills.
User	`~/.agents/skills/`	Personal Skills available across projects.
User native	`~/.client/skills/`	Client-specific personal Skills.

Trust and permissions

Project-level Skills come from the repository, which may be untrusted. Clients should consider folder trust, diagnostics, and permission allowlists before letting a Skill influence model behavior or read bundled resources.

Collision rulesProject Skills usually override user Skills with the same name.

Malformed filesWarn and skip invalid Skills rather than silently loading broken instructions.

Resource accessAllowlist approved Skill folders so referenced files can be read smoothly.

Cloud agentsProvision user or organization Skills because the sandbox may not see local files.

Beginner checks

The client should show the model a compact capability description, not the whole implementation.
The client should pass structured input, not a vague paragraph.
The client should handle empty results differently from server errors.
The client should preserve language choice and page route when moving between docs pages.