> ## Documentation Index
> Fetch the complete documentation index at: https://teamcopilot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Workflows & Skills

> Learn the difference between skills and workflows in TeamCopilot, how they work together, and when your organization should use each one.

TeamCopilot gives your organization two main ways to extend what the AI can do: **skills** and **workflows**.

* A **skill** tells the AI *how to think and operate* for a certain kind of task.
* A **workflow** tells the system *what code to run* for a certain kind of task.

Skills are best for reusable guidance and decision-making. Workflows are best for repeatable automation.

## What is a skill?

A skill is a set of instructions written in natural language, in a `SKILL.md` file. It acts as a reusable operating guide for the AI.

* It explains what the task is.
* It explains how the AI should approach that task.
* It can define rules, constraints, checks, and best practices.
* It can point the AI to relevant files, scripts, or resources.

Skills are especially useful when success depends on judgment, process, context, or organizational standards.

For example, a skill can tell the AI:

* how your team handles incident response
* how to prepare a customer-ready RCA
* how to validate a release before shipping
* what internal rules must be followed when making infrastructure changes

A skill does **not** need to contain executable logic. Its job is to shape the AI's behavior.

## What is a workflow?

A workflow is a runnable automation package, built around Python code. In TeamCopilot, it usually includes:

* a `workflow.json` file that describes the workflow
* a `run.py` entrypoint that performs the task
* optional inputs
* a runtime timeout
* an isolated Python environment and any supporting files the code needs

Workflows are useful when you want something to be:

* repeatable
* deterministic
* auditable
* parameterized with inputs
* runnable on demand without relying on the AI to re-create the logic every time

For example, a workflow can:

* generate a report from a database
* sync data between systems
* provision a standard resource
* run a scheduled or manual operations task
* perform a multi-step API integration reliably

## The core difference

Here is the practical difference:

| Topic           | Skill                                                      | Workflow                                                        |
| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| Primary purpose | Teach the AI how to handle a class of tasks                | Execute a concrete task in code                                 |
| Format          | Natural-language instructions in `SKILL.md`                | Python-based runnable package with `workflow.json` and `run.py` |
| Best for        | Judgment, standards, reasoning, process guidance           | Repeatable automation, integrations, deterministic steps        |
| Inputs          | Usually conversational context from the user and workspace | Explicit structured inputs defined in the workflow manifest     |
| Output style    | Varies based on the AI's response                          | Output from a scripted run                                      |
| Execution model | The AI reads and follows it                                | TeamCopilot runs the code                                       |
| Reusability     | Reusable playbook for similar tasks                        | Reusable automation for the same operation                      |

## How skills and workflows work together

A common pattern looks like this:

1. A **skill** tells the AI how to approach a task.
2. The skill explains when a **workflow** should be used.
3. The workflow performs the actual scripted execution.
4. The AI then interprets or communicates the result back to the user.

For example:

* A deployment skill can explain your release checklist, required validations, and rollback rules.
* A deployment workflow can perform the actual deployment steps against your systems.

In that setup, the skill gives the AI the playbook, and the workflow gives it the tool.

## When to use a skill

Use a skill when the main value is helping the AI behave correctly.

Choose a skill when:

* the task is mostly about instructions, judgment, or process
* you want the AI to follow your team's standards
* the steps may vary depending on context
* the task involves reviewing, reasoning, summarizing, planning, or decision support
* you want to guide the AI toward the right files, tools, or checks

## When to use a workflow

Use a workflow when the main value is reliable execution.

Choose a workflow when:

* the same task should run the same way each time
* you need code to call APIs, read systems, or transform data
* the task benefits from structured inputs and validation
* you want a task to run standalone, without the AI improvising the implementation
* you need a concrete execution record for an operation

## When to use both

Use both when the task needs AI judgment plus reliable automation.

* put the human-readable guidance in a **skill**
* put the repeatable code in a **workflow**

## A simple rule of thumb

Ask this question:

> Is this mainly something I want the AI to understand, or mainly something I want the system to run?

If the answer is **understand**, start with a **skill**.

If the answer is **run**, start with a **workflow**.

If the answer is **both**, use both.

## Recommended approach for most teams

When implementing TeamCopilot for your organization:

* start with **skills** for team-specific knowledge, rules, and ways of working
* add **workflows** for tasks that need reliability, external system access, or structured execution
* combine them for important operational flows where both guidance and automation matter

This gives you a practical operating model: **skills** capture how your team works, and **workflows** capture what your systems should do.