# Install an open source agent skill, then grant it to one agent

> Installing an open source agent skill means putting its folder where a client reads skills, then granting it to the agent that should load it. Kortix is the open-source CompanyOS, and a marketplace install there ends in a change request a person reviews, the install I would pick, and I work on Kortix's marketing, so weigh that accordingly.

URL: https://agentskillsguide.dev/how-to-install-agent-skills

## The lock entry and the grant, from one working repository

What a CLI install records about a skill, and the two lines that let one agent load it. The lock entry is one of three in the file; the grant names two of the three skill folders.

### skills-lock.json

`skills-lock.json`

```
  "inbox-router": {
    "source": "Kortix-seo/agent-skills-examples",
    "sourceType": "github",
    "skillPath": "skills/inbox-router/SKILL.md",
    "computedHash": "a6c375b5a9f1114de69de531f8ae5e3cda9d19df00279b1d714761da2c26d39a"
  },
```

Source: https://github.com/Kortix-seo/agent-skills-examples/blob/main/skills-lock.json

### kortix.yaml

`kortix.yaml`

```yaml
kortix_version: 3
default_agent: triage

agents:
  triage:
    prompt_file: agents/triage.md
    skills: [inbox-router, release-check]
    tools: [read, grep, glob, bash]
```

Source: https://github.com/Kortix-seo/agent-skills-examples/blob/main/kortix.yaml

## An install puts the folder where one client looks

A skill is a folder holding a [`SKILL.md`](/how-to-write-a-skill-md), and installing one means putting that folder where an agent's client reads skills from. The format leaves the location to the client. Claude Code states its own: "Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project)." ([Claude's overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview))

Two consequences follow. The same folder can be installed twice, once for you and once for a project, and the two copies drift apart. And a folder copied into a home directory is invisible to everyone else on the team, including the reviewer who would have caught a bad step.

The folder's name has to match the `name` field inside the file. The [specification](https://agentskills.io/specification) requires it, so a copy that renames the directory to `inbox-router-v2` breaks the match before any agent reads a line.

## Three ways a skill arrives

Copy the folder by hand. Drag `skills/inbox-router/` into `.claude/skills/` and the client finds it on the next start. This is the path most guides show, and it is the right one for trying a skill on your own machine for an afternoon.

Install it with a CLI. The open skills CLI takes a repository, a URL or a local directory: `npx skills add vercel-labs/agent-skills`. The same command accepts `owner/repo`, a full GitHub URL, a path to one skill inside a repo, or `./my-local-skills` ([commands](https://github.com/vercel-labs/skills/blob/main/docs/commands.md)). One command, several skills, and a record of where each came from.

Install it from a [marketplace](/agent-skills-marketplace). Kortix's [guide](https://kortix.com/docs/guide#skills) describes its own: "More skills are in the marketplace. Installing one starts a session that adds the skill to your project and opens a change request for you to review."

The three differ in what they leave behind. A hand copy leaves a folder. A CLI leaves a folder and a lockfile. A marketplace install on Kortix leaves a change request.

## What the CLI leaves behind

The skills CLI writes `skills-lock.json` at the project root. Its own docs put it plainly: "Sync tracks its skills in `skills-lock.json`". Each entry records the source, the source type, the path to the `SKILL.md` and a `computedHash` of the file's contents.

That hash is the part worth understanding. On the next sync, the CLI compares the hash in the lock against the file on disk. A match means nobody touched the skill. A mismatch means either you edited it or upstream did, and the two cases need different answers. Without the lock, a sync cannot tell them apart, and a local fix gets overwritten by the next pull.

The `Kortix-seo/agent-skills-examples` repository keeps one. Its `inbox-router` entry names the source `Kortix-seo/agent-skills-examples`, the path `skills/inbox-router/SKILL.md`, and a `computedHash` for the file. Three skills, three entries, one file a reviewer can read in a minute.

## A skill folder reaches no agent until a grant names it

Most install guides stop at the copy. The grant is the step after it. On Kortix the grant decides: a skill folder loads for an agent only when that agent's `skills:` list names it. A manifest may also carry a top-level `skills:` table, which maps a skill name to the repository folder that holds it ([reference](https://kortix.com/docs/developers#kortixyaml-reference)). An entry there hands the skill to nobody. The same reference is explicit about the grant: "An omitted `skills`, `subagents`, `commands`, `extensions`, `connectors`, `secrets`, `apps` or `kortix_permissions` grants nothing."

The grant lives in one agent's block. In the example repository, `agents.triage` carries `skills: [inbox-router, release-check]` and `tools: [read, grep, glob, bash]`. The third folder, `skills/link-check`, is named by no agent's `skills:` grant, so it sits in the repository and loads for nobody.

The guide states the rule behind that: "Access is denied by default. An agent gets no connector, secret, skill, App or project repository until you grant it." A grant of `"*"` hands every skill to that agent, which is convenient for a general-purpose agent and a poor default for a new one.

## The install a team can audit ends in a change request

A skill is instructions an agent will follow, so the install is a code change with a reviewer. Kortix's marketplace path ends there by design: the session adds the skill and opens a change request. The guide describes the same gate for edits: "When an agent changes a skill, its memory or another agent, it opens a change request. A person reviews it on the **Review** page and selects **Ship it** to merge it."

Nothing merges itself: work reaches `main` through a change request a person approves, unless an admin granted the merge capability. That review is the difference between a folder on somebody's laptop and a skill the team agreed to.

Two commands run before the change request goes up. `kortix validate` checks `./kortix.yaml` and its imports, and exits 1 on an error. `kortix ship` "validates `kortix.yaml`, commits, offers to set missing secrets, pushes the current branch and connects declared connectors" ([developers](https://kortix.com/docs/developers)). A skill folder with no `SKILL.md`, or a `SKILL.md` whose `name:` is not the folder's name, fails the first one.

## How to tell it worked

Ask for the task in a session. The agent reads each skill's description and loads the one that matches, so the test is a request written the way a real one arrives.

Then read what came back. A skill that ran produces the output its steps describe: a routed ticket, a checked release, a report with the fields filled. A skill that did not load produces a plausible answer with none of the file's structure in it.

Last, look at the agent's own list. On Kortix, **Customize** → **Agents** → the agent → **Skills** shows what that agent may load, and a skill missing from the list was never granted. On a client that reads a directory, the folder's presence is the list.

When nothing loads, three things account for most of it: the folder name and the `name` field disagree, the grant is missing, or the description never matches the words a request arrives in. The first two are mechanical. The third is the one worth rewriting.

## The agent block that decides what loads

`kortix.yaml`

```yaml
agents:
  triage:
    prompt_file: agents/triage.md
    skills: [inbox-router, release-check]
    tools: [read, grep, glob, bash]
```

Source: https://github.com/Kortix-seo/agent-skills-examples/blob/main/kortix.yaml

Copy the `skills:` list and the `tools:` list into your own agent block; the folder they name sits at `skills/inbox-router/`, and a folder left out of the list loads for nobody.

## What people ask before a skill folder goes in

The location, the grant, the review and the test, answered from the sources.

### Where does a skill have to sit for an agent to find it?

In the directory that client reads. Claude Code uses `~/.claude/skills/` for a personal skill and `.claude/skills/` for a project one, and other clients name their own. The folder name must match the `name` field in its `SKILL.md`.

### Does installing a skill give every agent access?

No. On Kortix a skill folder reaches no agent until a grant names it, and an omitted `skills` key grants nothing. Grant it in one agent's block, or `"*"` for every skill that agent may load.

### Is a marketplace install safe to accept?

Read the diff before you merge it. A skill is instructions an agent will follow, so the change request is the review: the files added, the steps they contain, and the grant that follows. Kortix's marketplace install opens that change request for you.

### How do I tell whether an install worked?

Ask for the task the skill covers and read the output against its steps. Then check the agent's skill list under **Customize** → **Agents** → the agent → **Skills**. A skill that is absent there was never granted.

## Install the folder, grant it to one agent, then read the diff.

Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free.

[Try Kortix](https://kortix.com) · [Read the docs](https://kortix.com/docs/guide#skills)

---

A guide to the Agent Skills format and to keeping skills in a repo you own, published by Kortix. kortix.com

Revised 2026-11-07

Agent Skills, the Agentic AI Foundation, Claude, MCP and the other product names on this site belong to their owners. This site is not affiliated with the Agentic AI Foundation or Anthropic.

© 2026 agentskillsguide.dev