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

# Skills

> Inject reusable instructions from local directories or git repositories

Skills let you inject context files, prompts, rules, and reference documentation into agent trials. A skill is a directory containing a `SKILL.md` file.

## How skills reach the agent

For each trial, Harbor:

1. Resolves local and Git skill sources on the host into individual skill directories.
2. Uploads each directory to `/harbor/skills/<skill-name>` in the agent sandbox. If the task declares [`environment.skills_dir`](/tasks/skills), Harbor uses that directory instead.
3. Passes the sandbox skills directory to the agent integration as `skills_dir` before agent setup.
4. Lets the integration register the skills in its native location or pass the directory directly to the agent runtime.

For example, the Codex integration copies them into `$HOME/.agents/skills`, while Claude Code uses `$CLAUDE_CONFIG_DIR/skills`. Custom agents receive the same `skills_dir` constructor argument and should register its contents during `setup()` or `run()`.

Job-provided skills are uploaded after the environment healthcheck and before agent setup. When multiple supplied skills have the same directory name, the last one wins. See [Tasks → Skills](/tasks/skills) to bundle skills directly into a task environment.

## Local skills

Pass a local directory path:

```bash theme={"system"}
harbor run -d <dataset> -a <agent> \
  --skill <path/to/skill>
```

The path can identify one skill containing `SKILL.md`, or a root whose immediate child directories each contain `SKILL.md`.

## Git skills

Instead of checking skills into every project, you can reference a git repository. Harbor clones the repo, resolves a commit SHA, and caches the result locally.

### Shorthand syntax

```bash theme={"system"}
# Default branch, reading skills from repo/skills/
harbor run --skill <org/repo> -a <agent> -d <dataset>

# Tag or branch, reading skills from repo/skills/
harbor run --skill <org/repo>@<ref> -a <agent> -d <dataset>
```

Shorthand always resolves to `github.com` and uses the repository's `skills/` directory.

### Full URL syntax

```bash theme={"system"}
# Default branch, reading skills from repo/skills/
harbor run --skill https://github.com/<org>/<repo> -a <agent> -d <dataset>

# Subdirectory within a repo (uses /tree/ref/path format)
harbor run --skill https://github.com/<org>/<repo>/tree/<ref>/<path/to/skill> \
  -a <agent> -d <dataset>
```

Plain repository URLs use the repository's `skills/` directory. The `/tree/<ref>/<subdir>` format lets you point at a specific subdirectory of a monorepo.

### Multiple skills

Use `--skill` multiple times to inject several skills. If two skills share the same directory name, the last one wins:

```bash theme={"system"}
harbor run \
  --skill <org/repo> \
  --skill <path/to/local-skill> \
  -a <agent> -d <dataset>
```

## Caching

Git skills are cached locally at `~/.cache/harbor/skills/<host>/<org>/<name>/<sha>/`. Once a commit is cached, subsequent runs skip the clone. Different subdirectories from the same repository and commit are handled automatically.

To clear the cache:

```bash theme={"system"}
rm -rf ~/.cache/harbor/skills
```

## Reproducibility

When a job runs, Harbor records each skill's provenance in the job lock file:

* **`name`** -- the skill directory name
* **`source`** -- local path used during the run
* **`digest`** -- SHA-256 content hash of all files in the skill
* **`git_url`** -- the source repository (for git skills)
* **`git_commit_id`** -- the resolved commit SHA (for git skills)

This ensures that job results are fully traceable back to the exact skill content that was used, even if the branch has since moved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.