How to Create Custom Skills and Tools for the Knowledge Catalog Enrichment Agent

The Knowledge Catalog enrichment agent supports extensibility through a declarative skill-and-tool architecture where developers define capabilities in SKILL.md files and implement logic via MCP-compatible executables registered in tools/mcp.json.

The GoogleCloudPlatform/knowledge-catalog repository provides an enrichment agent that automatically generates metadata for knowledge catalogs by combining LLM capabilities with specialized data retrieval tools. Creating custom skills and tools for the Knowledge Catalog enrichment agent allows you to integrate proprietary data formats, internal APIs, or custom parsers into the enrichment pipeline using the Metadata Code Protocol (MCP) interface.

Understanding the Skill-and-Tool Architecture

The enrichment agent operates on a clear separation between skills (declarative descriptions) and tools (executable implementations). According to the architecture defined in toolbox/enrichment/README.md, the agent discovers capabilities by reading configuration files that map skill names to MCP server binaries.

Tools Configuration (tools/mcp.json)

The agent loads a tools configuration file that maps each tool name to an executable command and its arguments. In tools/mcp.json (referenced from the enrichment directory), you register available tools under the mcpServers key, specifying the binary path and startup arguments. For example, the demo md-fileset binary receives the target directory via a --dir parameter.

Skill Definitions (SKILL.md)

Each skill resides in its own directory under tools/skills/<skill-name>/ and contains a SKILL.md file with YAML front-matter declaring the skill's metadata. The front-matter includes the skill name and description, while the body documents which MCP methods the associated tool exposes. The agent parses these files at runtime to understand what capabilities are available before invoking the corresponding tool.

MCP Method Interface

Custom tools must implement standard MCP methods that the agent uses to retrieve data. The reference implementation in toolbox/enrichment/src/tools/md/main.ts demonstrates three core methods:

• list_fileset_contents – Returns a list of available files or resources
• read_fileset_file – Retrieves the full contents of a specific file
• search_fileset_content – Performs content-aware searches across the fileset

These methods form the contract between the enrichment agent and your custom tooling.

Step-by-Step Guide to Creating a Custom Skill

Follow these steps to extend the Knowledge Catalog enrichment agent with custom capabilities, from directory creation to runtime registration.

Step 1: Create the Skill Directory Structure

Create a new directory under tools/skills/ using a descriptive name for your capability. For example, to create a SQL file analyzer:

mkdir -p tools/skills/sql-inspector

This directory will contain your SKILL.md definition and any supporting documentation.

Step 2: Define the SKILL.md Metadata

Create a SKILL.md file in your skill directory with YAML front-matter describing the skill's purpose and the MCP methods it utilizes:

---
name: sql-inspector
description: |
  Scans a directory of SQL files and extracts table-level lineage information.
---

The `sql-inspector` MCP server provides:

* **list_fileset_contents** – list all *.sql files.
* **read_fileset_file** – return the full text of a chosen file.
* **search_fileset_content** – find occurrences of `CREATE TABLE` or `INSERT INTO`.

The agent parses this file to understand what your skill offers before attempting to invoke the tool.

Step 3: Implement the MCP Server

Build an executable that implements the three required MCP methods. Your binary should accept command-line arguments (such as --dir to specify the working directory) and communicate via the MCP protocol. The reference implementation in toolbox/enrichment/src/tools/md/main.ts demonstrates how to structure these methods for file-based data sources.

Ensure your binary handles the MCP method calls appropriately and returns structured data that the enrichment agent can feed into its LLM prompts.

Step 4: Register in tools/mcp.json

Register your tool in the tools/mcp.json configuration file so the agent can locate and launch the executable:

{
  "mcpServers": {
    "sql-inspector": {
      "command": "../dist/sql-inspector",
      "args": ["--dir", "sql-files"]
    }
  }
}

The command path is relative to the location of tools/mcp.json, and args passes any required startup parameters to your binary.

Runtime Execution Flow

When you execute the enrichment command, the agent follows a strict discovery and invocation sequence:

1. Parse the user-provided prompt.md to identify which skills are referenced
2. Locate the skill definitions in tools/skills/<skill-name>/SKILL.md to validate available MCP methods
3. Launch the corresponding MCP servers defined in tools/mcp.json (e.g., starting your custom binary)
4. Invoke the required methods (list_fileset_contents, search_fileset_content, etc.) to gather data
5. Enrich the LLM prompt with retrieved information and generate metadata for the Knowledge Catalog

Run the enrichment process using the CLI:

kcagent enrich --catalog-path . --tools-path tools --prompt-path prompt.md

The agent automatically manages the lifecycle of your custom tool processes, invoking them as needed based on the skills referenced in the prompt.

Summary

• Skills are declarative definitions stored in tools/skills/<name>/SKILL.md with YAML front-matter describing capabilities and MCP methods.
• Tools are executable binaries registered in tools/mcp.json that implement the MCP interface through list_fileset_contents, read_fileset_file, and search_fileset_content.
• The enrichment agent in the GoogleCloudPlatform/knowledge-catalog repository discovers skills by parsing prompt files, validates them against SKILL.md definitions, and orchestrates tool execution via the MCP protocol.
• Custom implementations can reference toolbox/enrichment/src/tools/md/main.ts for the standard MCP method signatures and argument handling patterns.

Frequently Asked Questions

What is the difference between a skill and a tool in the Knowledge Catalog enrichment agent?

A skill is the declarative description stored in a SKILL.md file that tells the agent what capabilities exist and which MCP methods are available. A tool is the actual executable binary registered in tools/mcp.json that implements those methods and performs the data retrieval or processing work when invoked by the agent.

Which MCP methods must a custom tool implement?

According to the reference implementation in toolbox/enrichment/src/tools/md/main.ts, custom tools should implement three core MCP methods: list_fileset_contents for resource discovery, read_fileset_file for content retrieval, and search_fileset_content for filtered queries. These methods enable the agent to browse, read, and search your data source effectively.

How does the enrichment agent discover custom skills?

The agent reads the user-provided prompt.md file to identify referenced skills, then loads the corresponding SKILL.md files from the tools/skills/<skill-name>/ directories specified in the --tools-path parameter. The YAML front-matter in these files provides the metadata required for the agent to understand and invoke the associated tool.

Can I reuse existing binaries as tools without modifying them?

Yes, as long as the binary can be launched with command-line arguments (such as --dir for specifying the working directory) and implements or wraps the three required MCP methods (list_fileset_contents, read_fileset_file, search_fileset_content). You register the existing binary directly in tools/mcp.json without source modification, provided it conforms to the MCP communication protocol expected by the agent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}