Create Agent Catalog Source

Create Agent Catalog Source

Scan a repository for agent templates and metadata, then generate a custom agent catalog source compatible with the agents catalog service.

Usage:

• /create-agent-catalog-source — scan the current working directory
• /create-agent-catalog-source /path/to/repo — scan a local repository
• /create-agent-catalog-source https://github.com/org/repo — clone and scan a remote repository

Step 1: Resolve Input

Parse the argument passed by the user to determine the target repository path.

If the argument looks like a GitHub URL (starts with https://github.com/ or git@github.com:):

1. Generate a temporary directory path:

   TMPDIR=$(mktemp -d /tmp/agent-catalog-XXXXXX)

2. Clone the repository (shallow):

   git clone --depth 1 <url> "$TMPDIR"

3. If the clone fails, report the error and suggest the user clone manually and pass the local path instead. Stop.
4. Use $TMPDIR as the scan target. Remember to clean up at the end.

If the argument is a local path:

1. Verify the path exists:

   test -d <path>

2. If it does not exist, report the error and stop.
3. Use the provided path as the scan target.

If no argument is provided:

1. Use the current working directory as the scan target.

After resolving the target path, detect git metadata for repositoryUrl generation:

cd <target-path>
git remote get-url origin 2>/dev/null
git branch --show-current 2>/dev/null

If the directory is not a git repo, warn the user that repositoryUrl fields will be empty but continue.

Convert the git remote URL to an HTTPS base URL:

• git@github.com:org/repo.git → https://github.com/org/repo
• https://github.com/org/repo.git → https://github.com/org/repo
• Store the remote URL and branch name for later use when building repositoryUrl per agent.

Check the output directory:

test -d <original-cwd>/.agent-catalog

If .agent-catalog/ already exists, ask the user whether to overwrite or choose a different output path using AskUserQuestion. Store the chosen path as <output-dir> (default: <original-cwd>/.agent-catalog). All subsequent steps use <output-dir> when writing output files.

Step 2: Discover Agents — Convention Scan

Search the target repository for directories containing an agent.yaml file. This is the preferred agent metadata format. Inform the user:

"Scanning for agent.yaml files (preferred convention)..."

Find all agent.yaml files:

find <target-path> -name "agent.yaml" \
  -not -path "*/.git/*" \
  -not -path "*/.github/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/vendor/*" \
  -not -path "*/build/*" \
  -not -path "*/dist/*" \
  -not -path "*/__pycache__/*"

For each agent.yaml found:

1. Read the file content.
2. Extract known fields:
   • name (string, required)
   • displayName (string, optional)
   • framework (string, required)
   • description (string, required)
   • labels (string array, optional, default [])
   • logo (string, optional, default "")
   • env (object with required and optional string arrays, optional)
3. Note any additional top-level fields — these will become customProperties.
4. Check for a companion README.md in the same directory:

   test -f <agent-dir>/README.md

5. If README.md exists, read its full content for the readme field.
6. Compute the agent's relative path from the repo root (for repositoryUrl).

Collect all discovered agents into a list. Track for each:

• Relative path within the repo
• Parsed agent.yaml fields
• Whether README.md was found
• Any extra fields for customProperties
• Discovery source: "convention"

Validation per agent:

• If name is missing, derive it from the directory name (kebab-case).
• If framework is missing, flag it as needing user input.
• If description is missing, try to extract the first paragraph from README.md if available.

Always proceed to Step 3 (Heuristic Scan) regardless of how many agents the convention scan found. The heuristic scan may discover additional agents in non-standard formats (e.g., YAML files not named agent.yaml, or agents documented only in Markdown).

Step 3: Discover Agents — Heuristic Scan

This step always runs after the convention scan to find additional agents that may use non-standard file names or only have Markdown documentation.

Inform the user:

"Scanning for additional agents via YAML heuristic and Markdown analysis..."

3a: YAML Heuristic Scan

Search for YAML files that look like they describe an agent:

find <target-path> -type f \( -name "*.yaml" -o -name "*.yml" \) \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/vendor/*" \
  -not -name "docker-compose*" \
  -not -name "*lock*" \
  -not -name ".pre-commit*"

For each YAML file, read it and check if it is "agent-like":

• It must contain a name field (string)
• It must contain at least one of: framework, description, or env
• Exclude files that look like CI configs, Dockerfiles, Kubernetes manifests (check for apiVersion, kind, services, jobs, steps top-level keys — these are not agents)

For qualifying files:

• Extract the same known fields as the convention scan
• Set discovery source to "yaml-heuristic"
• Note the file path

3b: Markdown Scan

Search for Markdown files that describe agents:

find <target-path> -type f -name "*.md" \
  -not -path "*/.git/*" \
  -not -path "*/node_modules/*" \
  -not -name "CHANGELOG*" \
  -not -name "LICENSE*" \
  -not -name "CONTRIBUTING*"

For each Markdown file, scan for agent-relevant signals:

1. Framework mentions — search (case-insensitive) for: langgraph, crewai, autogen, llamaindex, llama-index, haystack, semantic-kernel, langflow, langchain, openai-agents, google-adk, a2a

2. Agent keywords — search for: agent, tool-calling, ReAct, chain-of-thought, orchestrator, agentic, function calling, tool use

3. Environment variable documentation — look for sections with headers like "Environment Variables", "Configuration", "Setup", ".env" that list variable names

4. Description extraction — extract the first paragraph after the top-level heading as a candidate description

A Markdown file is a candidate if it has at least one framework mention AND at least one agent keyword.

For qualifying Markdown files, extract as many of the 7 required catalog fields as possible:

• name — infer from the filename or first heading (kebab-cased)
• displayName — infer from the first heading (original casing)
• framework — from the framework mention found
• description — from the first paragraph after the top-level heading
• labels — default [] (user can add during confirmation)
• logo — default "" (user can provide during confirmation)
• env — extract from environment variable documentation: look for bullet lists or tables listing variable names. Parse required/optional indicators from the text (e.g., "required", "optional", "Yes", "No"). If a var is listed without an indicator, default to required: true
• Set readme to the full file content
• Set discovery source to "markdown-inference"
• Flag all fields as draft — the user must confirm/edit

Merge Results

Combine convention-scan, YAML-heuristic, and markdown-inference results into a single list:

1. Deduplicate: If a heuristic/markdown candidate is from the same directory as a convention-scan agent, skip the heuristic candidate (convention already captured it).
2. Merge within heuristic: If a YAML-heuristic candidate and a markdown-inference candidate are from the same directory, merge them — prefer YAML fields, supplement with Markdown-extracted description/readme.

Proceed to Step 3c (Generate agent.yaml) with the merged list.

If zero agents total after all scans, tell the user:

"No agents found in this repository. To use this skill, organize your agents with an agent.yaml file per agent directory. Here is the expected format:"

Then print an example agent.yaml:

name: my-agent
displayName: My Agent
framework: langgraph
description: A custom agent that does X
labels:
  - tool-calling
  - rag
env:
  required:
    - API_KEY
    - MODEL_ENDPOINT
  optional:
    - DEBUG

And stop.

3c: Generate agent.yaml for Heuristic-Discovered Agents

Every agent in the catalog must have an agent.yaml file. Convention-scanned agents already have one. For each agent discovered via yaml-heuristic or markdown-inference, generate an agent.yaml matching the format expected by the agents catalog.

Important: The generated agent.yaml is NOT written to the agent's source directory — it is assembled in memory and included only in the catalog output (as the templates entry in <output-dir>/catalog.yaml). The agent's source directory remains unchanged.

For each heuristic/markdown-discovered agent:

1. Assemble the agent.yaml content from the extracted metadata using this exact format:

   name: <kebab-case-name>
   displayName: "<Human Readable Display Name>"
   framework: <framework>
   description: "<description>"
   labels: [<labels-as-inline-array-or-empty>]
   logo: "<logo-string-or-empty>"
   env:
     required:
       - VAR_NAME_1
       - VAR_NAME_2
     optional:
       - VAR_NAME_3

   Field mapping:

   • name: from extracted metadata, kebab-cased
   • displayName: from extracted metadata, or title-cased from name if not available
   • framework: from extracted metadata
   • description: from extracted metadata
   • labels: from extracted metadata, default []
   • logo: from extracted metadata, default ""
   • env.required / env.optional: from extracted environment variable documentation. If no env vars were found, use required: [] and optional: []

2. Display the generated agent.yaml to the user:

   "Generated agent.yaml for agent <name> (discovered via <source>):"

   <full assembled content>

3. Use AskUserQuestion to ask the user to confirm:

   • "Accept (Recommended)" — the generated agent.yaml is correct
   • "Deny" — reject this agent; it will be excluded entirely from the catalog

4. If the user chooses Accept:

   • Ask: "Would you like to amend any fields before finalizing? (y/N)"
   • If yes: let the user specify which fields to change and their new values. Update the assembled content. Display the updated version for final confirmation.
   • Store the confirmed agent.yaml content for use in Step 5 (templates field).

5. If the user chooses Deny:

   • Remove this agent from the discovered agents list.
   • Inform the user:

     "Agent <name> has been excluded from the catalog."

6. After processing all heuristic/markdown agents, report the final count:

   "N agents confirmed with agent.yaml files. Proceeding to catalog source configuration."

   If all heuristic/markdown agents were denied and no convention agents exist either, stop with the same "No agents found" message as above.

Proceed to Step 4 with only the confirmed agents.