Skip to main content

Workflows and reference

Last updated on

Skills chain together for multi-step workflows, and each skill file follows a consistent internal structure. This page covers common workflow sequences and the reference material for authoring or extending skills.

What will you learn in this topic?​

By the end of this topic, you will be able to:

End-to-end workflows​

Resources that depend on other resources must be created in the correct order.

New microservice setup​

Use these skills in order:

  1. /create-connector: Git, Docker registry, and Kubernetes cluster connectors.
  2. /create-secret: Credentials for connector authentication.
  3. /create-service: Service definition referencing connectors.
  4. /create-environment: Target environment configuration.
  5. /create-infrastructure: Infrastructure definition for the target cluster.
  6. /create-pipeline: CI/CD pipeline referencing the service, environment, and infrastructure.
  7. /create-trigger: Webhook or schedule trigger to automate the pipeline.

Debug a failed deployment​

Typical sequence:

  1. /run-pipeline: Identify the latest execution or reproduce the issue.
  2. /debug-pipeline: Classify the failure and inspect the root cause.
  3. /template-usage: Check if shared templates propagated the issue.
  4. /manage-delegates: Investigate delegate capacity or connectivity if relevant.

Codebase-aware pipeline generation​

The /create-pipeline skill includes codebase analysis capabilities. It scans your project files to auto-detect:

  • Language and runtime from source files (package.json maps to Node.js, go.mod maps to Go).
  • Build tools from build configuration (Dockerfile, webpack.config.js, pom.xml).
  • Test frameworks from test configuration (jest.config.*, pytest.ini).
  • Deployment targets from manifests (Chart.yaml maps to Helm, task-definition.json maps to ECS).

This allows the skill to generate pipeline YAML tailored to your project without manual configuration.

Skill anatomy​

Each skill lives in skills/<skill-name>/SKILL.md and follows a consistent structure. Knowing this structure helps you read existing skills and author your own.

skills/create-pipeline/
├── SKILL.md              # Skill definition (required)
└── references/           # Supplementary docs (optional)
    ├── native-steps.md
    ├── v0-pipeline-schema.md
    └── codebase-analysis.md

The SKILL.md file contains:

  • Frontmatter: Name, description, version, MCP server dependency, and license metadata.
  • Instructions: Phase-based steps with MCP tool calls and parameters.
  • Examples: Real invocation scenarios and worked examples.
  • Performance notes: Validation checks, tradeoffs, and optimization guidance.
  • Troubleshooting: Common errors and recovery steps.

Reference files in the references/ subdirectory provide supplementary knowledge, such as schema definitions, decision trees, and template libraries, that the AI loads on demand.

MCP tools​

Skills use the Harness MCP Server, which provides 11 generic tools dispatched by resource_type.

ToolPurpose
harness_listList resources.
harness_getGet resource details.
harness_createCreate a resource.
harness_updateUpdate a resource.
harness_deleteDelete a resource.
harness_executeExecute an action.
harness_searchSearch across resources.
harness_describeGet resource schema.
harness_schemaFetch JSON Schema definitions.
harness_diagnoseDiagnose issues.
harness_statusCheck system status.

Project structure​

The repository groups skills, shared references, and examples into a predictable layout.

harness-skills/
├── skills/
│   ├── create-pipeline/
│   │   ├── SKILL.md
│   │   └── references/
│   ├── create-template/
│   │   └── SKILL.md
│   ├── debug-pipeline/
│   │   └── SKILL.md
│   └── ...
├── references/              # Shared repo-level playbooks
├── templates/               # Shared repo-level output templates
├── examples/
│   ├── v0/                  # v0 pipeline examples
│   ├── v1/                  # v1 pipeline examples
│   ├── templates/
│   ├── triggers/
│   ├── services/
│   ├── environments/
│   ├── connectors/
│   └── ...
├── .cursor/rules/harness.mdc
├── .github/copilot-instructions.md
├── AGENTS.md
├── CLAUDE.md
└── CONTRIBUTING.md