Understanding the index.json File in the Google Skills Repository

The index.json file is a generated manifest that serves as the single source of truth for the catalog of skills in the google/skills repository.

The google/skills repository maintains a structured collection of AI-agent capabilities, and the index.json file plays a critical role in making these discoverable. This generated JSON document enumerates every skill contained in the repository, providing metadata that enables programmatic access without requiring tools to parse individual markdown files. Understanding the purpose of the index.json file in the google/skills repo is essential for developers building integrations or automation around this skill catalog.

Generated Manifest Structure

The index.json file follows a predictable schema designed for machine readability. It acts as a centralized registry that maps skill identifiers to their documentation and implementation details.

The Generator Field

At the top of the file, a "generator" field explicitly warns developers not to edit the contents manually. This warning exists because the file is produced automatically by the repository's build process. Any manual modifications would be overwritten during the next automated generation cycle, making direct edits both futile and potentially disruptive to dependent tooling.

The Skills Array

The core of the manifest is the "skills" array, which contains an object for every skill in the repository. Each entry provides three critical pieces of metadata:

• name: The unique identifier for the skill
• description: A concise summary of what the skill does
• entrypoint: The URL path to the markdown document that defines the skill (typically located within skills/…/SKILL.md)

This structure allows external tools to build search indexes, generate documentation, or populate IDE interfaces without scanning the entire filesystem.

How index.json Powers Skill Discovery

The primary purpose of index.json is to enable tooling that discovers, catalogs, and renders skills. Documentation generators, command-line interfaces, and IDE extensions rely on this manifest for quick lookups of available capabilities.

By consulting index.json, these tools avoid the performance cost and complexity of recursively parsing markdown files scattered across the skills/ directory. Instead, they consume the single JSON endpoint to enumerate options, fetch descriptions, and resolve paths to full skill definitions stored in individual SKILL.md files.

Working with index.json Programmatically

Developers can leverage the manifest to build custom integrations or automation scripts. The following examples demonstrate how to consume index.json using Python and JavaScript.

Loading the Manifest Locally

To parse the file from a local clone of the repository:

import json, pathlib, urllib.request

# Load the local copy

manifest_path = pathlib.Path("index.json")
data = json.loads(manifest_path.read_text())

# Print each skill name and its description

for skill in data["skills"]:
    print(f"{skill['name']}: {skill['description']}")

Fetching the Manifest from GitHub

For tools that do not maintain a local clone, you can fetch the manifest directly from the raw GitHub URL:

import json, urllib.request

url = "https://raw.githubusercontent.com/google/skills/main/index.json"
with urllib.request.urlopen(url) as resp:
    data = json.load(resp)

# Find the entrypoint for a specific skill

skill_name = "agent-platform-deploy"
entry = next(s for s in data["skills"] if s["name"] == skill_name)
print(entry["entrypoint"])

Generating HTML Documentation

The following JavaScript example renders the skill catalog as an HTML table:

fetch('index.json')
  .then(r => r.json())
  .then(manifest => {
    const table = document.createElement('table');
    manifest.skills.forEach(s => {
      const row = table.insertRow();
      row.insertCell().textContent = s.name;
      row.insertCell().textContent = s.description;
      const link = document.createElement('a');
      link.href = s.entrypoint;
      link.textContent = 'Docs';
      row.insertCell().appendChild(link);
    });
    document.body.appendChild(table);
});

Relationship to Individual Skill Files

While index.json provides the metadata catalog, it does not contain the actual skill definitions. The "entrypoint" field in each skills array element references a markdown file located within the skills/ directory tree, typically named SKILL.md.

This separation of concerns allows the manifest to remain lightweight and quickly parsable, while the detailed implementation guides, parameters, and examples reside in their respective documentation files. When a tool needs full details about a specific skill, it uses the entrypoint path to fetch the corresponding markdown document.

Summary

• index.json is a machine-generated manifest that catalogs all skills in the google/skills repository.
• The file contains a "generator" warning against manual editing and a "skills" array with name, description, and entrypoint metadata.
• It serves as the single source of truth for programmatic skill discovery, eliminating the need to parse individual markdown files.
• The "entrypoint" field links to specific skills/…/SKILL.md files where full skill definitions reside.
• Tools use this manifest to build CLI interfaces, IDE extensions, and documentation generators efficiently.

Frequently Asked Questions

Is the index.json file manually editable?

No. The index.json file contains a "generator" field that explicitly warns developers not to edit it manually because the contents are produced automatically by the repository's build process. Any manual changes would be overwritten during subsequent automated generations.

What information does each skill entry contain?

Each object in the "skills" array contains three fields: the name (unique identifier), a description (concise summary), and the entrypoint (URL path to the skill's markdown definition file). This standardized structure enables consistent programmatic access across different tools and integrations.

How does index.json improve tool performance?

Rather than recursively scanning and parsing all markdown files in the skills/ directory, tools can consume the single index.json file to enumerate available capabilities. This approach provides O(1) access to the full catalog and eliminates the computational overhead of filesystem traversal and markdown parsing for simple discovery tasks.

Where are the actual skill definitions stored?

The skill definitions are stored in individual markdown files, typically named SKILL.md, located within subdirectories of the skills/ folder. The index.json file references these locations via the "entrypoint" field, creating a lightweight index that points to detailed documentation without duplicating its content.

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