Konstruct

Package manager for AI agent skills. Manages the lifecycle of skill directories — discovery, installation, updating, and removal — across one or more AI agent tool directories.

Add Skills

npx konstruct add owner/repo

Install

npm install -g konstruct

Quick Start

# Initialize a project
konstruct init

# Add a skill from GitHub
konstruct add anthropics/skills

# Add a specific skill from repo
konstruct add anthropics/skills --skill skill-creator

# Install all skills from skills.json
konstruct install

# Check for updates
konstruct update

# List installed skills
konstruct list

Features

Declarative Manifest

Every project gets a skills.json that declares exactly which skills it needs and where they come from. Run konstruct install on any machine and get the same setup — no manual steps.

{
  "name": "my-project",
  "version": "1.0.0",
  "skills": {
    "canvas-design": {
      "source": "anthropic/skills/canvas-design#v1.0"
    },
    "data-analytics": {
      "source": "github:company/analytics-repo/skills/analytics#main"
    }
  },
  "userSkills": {
    "my-local-skill": {
      "source": "file:./local-skills/my-skill"
    }
  }
}

Default Agents

Configure which agents receive skills so you don't have to specify them every time. Set defaults at the project or global level with konstruct defaults, or let them resolve automatically:

1. Project config (./konstruct.config.json) agents
2. Global config (~/.konstruct/konstruct.config.json) default agents
3. Fallback: claude

{
  "version": 1,
  "agents": ["claude", "cursor"],
  "global": {
    "defaultAgents": ["claude"]
  }
}

Private Skils

Konstruct can install skills from private repositories as long as your local machine is authenticated. HTTPS uses your existing git credentials (e.g. gh auth login), or you can use SSH:

# Private repo over HTTPS (uses your local git credentials)
konstruct add github:my-org/private-skills

# Private repo over SSH
konstruct add github:my-org/private-skills --ssh

Global and Project Configuration

Konstruct operates at two scopes. Project-level config lives in your repo and tracks which agents that project uses. Global config lives at ~/.konstruct/ and provides defaults for all projects.

# Project scope (default)
konstruct init
konstruct add anthropic/skills/canvas-design#main

# Global scope
konstruct init -g
konstruct add -g anthropic/skills/canvas-design#main

Every command supports -g, --global to switch between scopes.

Custom Install Paths

Override where a skill gets installed with --path. The path is saved in the manifest so subsequent konstruct install and konstruct update calls respect it.

konstruct add github:org/repo --path /opt/shared-skills

{
  "skills": {
    "repo": {
      "source": "github:org/repo",
      "path": "/opt/shared-skills"
    }
  }
}

Local Skills

Add skills from your local filesystem with --user. These are kept in a separate userSkills section of the manifest and are never auto-updated, making them ideal for private or in-development skills.

konstruct add file:./my-private-skill --user

Skills are separated into two categories:

	Installed Skills	User Skills
Sources	GitHub, GitLab, any git URL	Local filesystem only
Updates	Auto-updated via konstruct update	Never auto-updated
Use case	Shared, versioned skills	Private, local, or experimental
Flag	(default)	--user

Both types are installed when running konstruct install, but konstruct update only touches git-based skills.

Commands

Command	Description
konstruct init	Create skills.json and konstruct.config.json
konstruct add <source>	Add a skill from a git or local source
konstruct install	Install all skills from skills.json
konstruct update	Re-install git skills at their manifest refs
konstruct remove <names...>	Remove one or more skills by name
konstruct list	List all skills in the current manifest
konstruct defaults	View and update default agent preferences

Options

• -g, --global — Use global ~/.konstruct/ directory
• -s, --ssh — Use SSH for git cloning (default: HTTPS with auto-retry)
• --user — Add as a user skill (local, never auto-updated)
• --path <path> — Custom installation path

Source Formats

Format	Example
GitHub	github:owner/repo/path#ref
GitLab	gitlab:owner/repo#ref
Generic git	git:https://host/repo.git#ref
Local file	file:./relative/path
Bare shorthand	owner/repo (defaults to GitHub)

Supported Agents

Konstruct installs skills into the appropriate directory for each agent:

claude, cursor, windsurf, continue, copilot, gemini, augment, cline, goose, junie, kiro, opencode, openhands, roo, trae, kode, qwen-code, codex, amp, kilo, pochi, neovate, mux, zencoder, adal

License

MIT