Concepts

The building blocks of equip: skills, sources, agents, and scopes.

Skills

A skill is a directory containing a SKILL.md file. The SKILL.md provides instructions that AI coding agents read and follow. Think of it as a reusable prompt that teaches an agent how to perform a specific task.

SKILL.md format

Every SKILL.md starts with YAML frontmatter, followed by markdown content:

---
name: my-skill
description: What this skill does
---

# My Skill

Instructions for AI agents go here.
When an agent reads this file, it follows
these instructions to perform the task.

The frontmatter fields:

Field	Required	Description
`name`	Yes	Unique identifier for the skill (kebab-case)
`description`	Yes	One-line summary of what the skill does

Skill directory structure

A skill directory can optionally include supporting files:

my-skill/
  SKILL.md           # Required — skill instructions
  references/        # Optional — reference documents the agent can read
    api-spec.md
    examples.md
  scripts/           # Optional — scripts the agent can run
    validate.sh
  assets/            # Optional — other supporting files
    template.json

Note

Skills managed by equip should not be edited directly in their installed location. Edit the source repo instead, then run equip update to pull changes.

Sources

A source is where a skill comes from. equip supports three source types:

Type	Format	Example
GitHub repo	`owner/repo`	`anthropics/skill-creator`
Git URL	`https://...` or `git@...`	`https://github.com/user/repo.git`
Local path	`./path` or `/absolute/path`	`./my-skills/commit`

Subpaths

When a repository contains multiple skills in subdirectories, specify a subpath:

$ equip install anthropics/skills/skills/pdf
# Installs just the "pdf" skill from the anthropics/skills repo

equip tracks which source each skill came from, so equip update knows where to pull from.

Agents

An agent is an AI coding tool that reads SKILL.md files. equip supports 18 agents and auto-detects which ones are installed on your machine by checking for their configuration directories.

When you run equip install, the skill is copied to every detected agent's skills directory. See Agents for the full list and directory paths.

Targeting specific agents

Install to specific agents only:

$ equip install owner/repo --agent claude,cursor

Or install to all 18 agents regardless of detection:

$ equip install owner/repo --all

Scopes

Skills can be installed in two scopes:

Global scope (default)

Global skills are installed to each agent's home directory (e.g., ~/.claude/skills/) and are available in every project.

$ equip install owner/repo
# Installs to ~/.claude/skills/, ~/.cursor/skills/, etc.

Project-local scope

Project-local skills are installed to agent directories within the current working directory and only apply to that project.

$ equip install owner/repo --local
# Installs to .claude/skills/, .cursor/skills/, etc. in the current directory

Most commands accept --local to operate on project-local skills: list, remove, update, outdated, survey.

Tip

Project-local skills are useful for team-specific workflows. Commit the .claude/skills/ (or equivalent) directory to version control so everyone on the team gets the same skills.