Create Agent Template Skill

Generate Harness Agent Template files for AI-powered automation agents.

Instructions

1. Identify the agent's purpose - What task should the agent automate (code review, security scanning, test generation, documentation)?
2. Define inputs and configuration - What parameters does the agent need (repo, branch, connector, secrets)?
3. Generate three files - metadata.json (template metadata), pipeline.yaml (v1 syntax), and wiki.MD (user documentation)
4. Validate consistency - Ensure input references in pipeline.yaml match definitions in metadata.json

Overview

Agent templates are modular pipeline definitions that encapsulate AI-powered automation. Each template produces three files:

File	Required	Purpose
metadata.json	Yes	Template name, description, version
pipeline.yaml	Yes	Pipeline definition (v1 syntax)
wiki.MD	Recommended	User-facing documentation

Directory Structure

templates/<agent-name>/
  metadata.json
  pipeline.yaml
  wiki.MD

metadata.json

{
  "name": "Agent Name",
  "description": "Brief description of what this agent does (1-2 sentences)",
  "version": "1.0.0"
}

Rules:

• name: Sentence Case (Code Review, not code-review)
• description: Under 200 characters, clear value proposition
• version: Semantic versioning MAJOR.MINOR.PATCH

pipeline.yaml

Core Structure

version: 1
pipeline:
  clone:
    depth: 1
    ref:
      name: <+inputs.branch>
      type: branch
    repo: <+inputs.repo>
    connector: "<+inputs.gitConnector != null ? inputs.gitConnector.id : ''>"

  stages:
    - name: <stage-name>
      steps:
        - name: <step-name>
          run:
            container:
              image: <registry>/<image>:<tag>
            with:
              param: value
            env:
              SECRET_VAR: <+inputs.secretInput>
      platform:
        os: linux
        arch: arm64

  inputs:
    repo:
      type: string
      required: true
    branch:
      type: string
      default: main
    llmConnector:
      type: connector
    gitConnector:
      type: connector

Clone Configurations

Branch clone:

clone:
  depth: 1
  ref:
    name: <+inputs.branch>
    type: branch
  repo: <+inputs.repo>
  connector: "<+inputs.gitConnector != null ? inputs.gitConnector.id : ''>"

Pull request clone:

clone:
  depth: 1000
  ref:
    type: pull-request
    number: <+inputs.pullReq>
  repo: <+inputs.repo>

Input Types

Type	Usage	Example
string	Text values	repo name, branch, file paths
secret	Sensitive values	API keys, tokens
connector	Harness connectors	Git connector, LLM connector

inputs:
  repo:
    type: string
    required: true
  branch:
    type: string
    default: main
    description: Branch to analyze
  apiKey:
    type: secret
    default: account.my_secret
  llmConnector:
    type: connector
    description: LLM provider connector
  gitConnector:
    type: connector
    description: Git repository connector

Step Types

Container plugin step:

- name: my-step
  run:
    container:
      image: registry/image:tag
    with:
      plugin_param: value
    env:
      API_KEY: <+inputs.apiKey>

Shell script step:

- name: shell-step
  run:
    shell: bash
    script: |-
      echo "Running script"
      git add -A
      git diff --cached
    env:
      MY_VAR: value

Expression Syntax

# Input references
<+inputs.variableName>

# Connector token
<+inputs.connectorName.token>

# Step outputs
<+pipeline.stages.STAGE.steps.STEP.output.outputVariables.VAR>

# Environment variables
<+env.HARNESS_ACCOUNT_ID>
<+env.HARNESS_ORG_ID>
<+env.HARNESS_PROJECT_ID>

# Alternative syntax for inputs in env blocks
${{inputs.repo}}

wiki.MD

# Agent Name

**Version:** 1.0.0
**Name:** Agent Name

## Overview

What this agent does and why it is useful.

---

## Key Capabilities

- **Capability 1**: Description
- **Capability 2**: Description

---

## How It Works

1. **Step 1**: Description
2. **Step 2**: Description
3. **Step 3**: Description

## Required Inputs

| Input | Type | Description | Default |
|-------|------|-------------|---------|
| `repo` | string | Repository identifier | -- |
| `branch` | string | Branch to analyze | main |

## Usage Example

\`\`\`yaml
inputs:
  repo: "my-org/my-repo"
  branch: "main"
\`\`\`

## Troubleshooting

### Common Issue 1
Solution description.

Complete Examples and Common Patterns

For complete agent examples (Code Review, Security Scanner, Documentation Generator) and reusable patterns (SCM detection, coding agent, PR creation), consult references/agent-examples.md.

Examples

Create a code review agent

/create-agent-template
Create an agent template for code review that analyzes pull requests,
provides feedback, and posts review comments

Create a security scanner agent

/create-agent-template
Generate a security scanner agent that finds vulnerabilities and
creates a report

Create a documentation generator

/create-agent-template
Create an agent that analyzes a codebase and generates documentation,
then opens a PR with the results

Create a test generator

/create-agent-template
Build an agent template that generates unit tests to improve code coverage

Error Handling

Error	Cause	Solution
Invalid metadata	Missing name, description, or version	Include all three required fields
Invalid version	Not semver format	Use MAJOR.MINOR.PATCH (e.g., 1.0.0)
Pipeline validation error	Invalid v1 YAML syntax	Verify pipeline structure follows v1 schema
Connector not found	Referenced connector does not exist	Create the connector before running the agent
Undefined input reference	<+inputs.x> used but x not defined in inputs	Add missing input definition

Performance Notes

• Validate all three generated files (metadata.json, pipeline.yaml, wiki.MD) are consistent with each other.
• Ensure the pipeline YAML uses correct v1 syntax with lowercase types and ${{ }} expressions.
• Test that all input references in the pipeline match the inputs defined in metadata.json.

Troubleshooting

Agent Not Executing

1. Verify all required: true inputs have values
2. Check connector inputs are valid and accessible
3. Confirm container images exist and are accessible from the build infrastructure

SCM Provider Detection Failing

1. Verify DRONE_REPO_SCM environment variable is available
2. Check that connector tokens have correct permissions
3. Test with a known SCM provider before adding multi-provider logic

PR Creation Failing

1. Confirm git changes exist (git diff --cached is non-empty)
2. Verify the token has write access to create branches and PRs
3. Check that PLUGIN_REPO format matches the SCM provider expectations

Output Variables Not Available

1. Write outputs using echo "KEY=value" >> $DRONE_OUTPUT
2. Write secret outputs using echo "KEY=value" >> $HARNESS_OUTPUT_SECRET_FILE
3. Reference with full path: <+pipeline.stages.STAGE.steps.STEP.output.outputVariables.KEY>

Best Practices

• Never hardcode secrets -- use type: secret inputs
• Use type: connector for authentication rather than raw tokens
• Include meaningful descriptions on all inputs
• Keep stages focused on single responsibilities
• Always include the SCM detection pattern for multi-provider support
• Store secret outputs with $HARNESS_OUTPUT_SECRET_FILE, not $DRONE_OUTPUT
• Set depth: 1000 for PR clones to ensure full diff history
• Set depth: 1 for branch clones to minimize clone time