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 you will learn in this topic​

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

Before you begin​

Before you chain skills into a workflow, ensure you have the following:

  • Configured skills: An AI coding assistant set up to load skill instructions. For more information, see Set up skills.
  • Harness MCP Server: A configured MCP server for tool execution.
  • Skill catalog familiarity: Knowledge of which skills cover the resources in your workflow. For more information, see Skill catalog.

End-to-end workflows​

Most real tasks span several skills rather than one. Resources that depend on other resources must be created in the correct order, so the sequences below invoke skills in an order that satisfies those dependencies.

New microservice setup​

Start with the resources that nothing else depends on, then work up to the pipeline and trigger that reference them.

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​

Start debugging the failed execution, and then widen the investigation to the shared templates and delegates the pipeline depends on.

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​

Some skills read your repository directly, so they infer context from your code in addition to the detail you supply in the prompt.

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