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

> Learn to create custom skills and tools for the Knowledge Catalog enrichment agent using a declarative skill and tool architecture. Extend your catalog's capabilities today.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-14

---

**The Knowledge Catalog enrichment agent supports extensibility through a declarative skill-and-tool architecture where developers define capabilities in [`SKILL.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/SKILL.md) files and implement logic via MCP-compatible executables registered in [`tools/mcp.json`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash
mkdir -p tools/skills/sql-inspector

```

This directory will contain your [`SKILL.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/SKILL.md) definition and any supporting documentation.

### Step 2: Define the SKILL.md Metadata

Create a [`SKILL.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/SKILL.md) file in your skill directory with YAML front-matter describing the skill's purpose and the MCP methods it utilizes:

```markdown
---
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tools/mcp.json) configuration file so the agent can locate and launch the executable:

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

```

The `command` path is relative to the location of [`tools/mcp.json`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/SKILL.md) definitions, and orchestrates tool execution via the MCP protocol.
- Custom implementations can reference [`toolbox/enrichment/src/tools/md/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/prompt.md) file to identify referenced skills, then loads the corresponding [`SKILL.md`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tools/mcp.json) without source modification, provided it conforms to the MCP communication protocol expected by the agent.