Gart NPM

Dependencies that teach your AI how to use them.

Gart extends npm to distribute AI usage knowledge alongside your dependencies.

When you add a library, you usually get only code and have to figure out how to use it yourself.

Gart changes that.

It allows library authors to package AI skills together with their artifacts, so when a dependency is added, its usage knowledge can be resolved and installed automatically for your AI tools.

Why Gart Exists

Adding a dependency gives you code, but not understanding.

• Documentation is static and often incomplete
• Examples cover only basic scenarios
• Best practices live in people’s heads
• AI assistants guess instead of knowing

This leads to slow onboarding, inconsistent usage, and fragile integrations.

What Gart Does

Gart introduces a new concept: skills as dependencies.

With Gart:

• libraries publish AI-readable usage knowledge
• knowledge is versioned together with the artifact
• npm projects resolve and install it automatically
• AI assistants can use it to generate correct code

Dependencies are no longer just code. They carry their own knowledge.

Quick Example

Install the CLI package:

npm install --save-dev @garthub/gart-npm

Declare skill dependencies:

// gart.config.js
module.exports = {
	resolution: {
		repositories: [
			{
				type: 'maven',
				url: 'http://localhost:5151/repository/garthub/',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:payment-sdk:1.2.0'],
		},
	},
};

After resolution, skills are installed into:

.agents/skills

Your AI assistant can now use them to generate correct integration code.

What This Package Does

@garthub/gart-npm integrates Gart into an npm-based project.

It allows your project to:

• package local skills into a distributable artifact (*-skills.zip)
• publish skills to Maven-style repositories
• resolve skill dependencies from Maven-style repositories
• install resolved skills into .agents/skills
• make them available for AI tools

In short:

npm manages your JavaScript dependencies.

Gart manages your AI knowledge dependencies.

Basic Project Setup

Install:

npm install --save-dev @garthub/gart-npm

By default, Gart reads local skills from:

skills/

You can add more directories:

// gart.config.js
module.exports = {
	srcDirs: ['skills', 'extra-skills', 'generated-skills'],
};

Recommended scripts:

{
	"scripts": {
		"gart:resolve": "gart resolve",
		"gart:clean": "gart clean",
		"gart:build": "gart build",
		"gart:publish": "gart publish"
	}
}

resolve is also triggered automatically through postinstall when the package is installed in a consumer project.

Commands

• gart resolve — resolves skill dependencies
• gart clean — removes Gart-managed skills
• gart build — builds the *-skills.zip archive
• gart publish — builds and publishes the archive together with its Maven POM

Configuration

Recommended precedence:

1. gart.config.js
2. gart.config.cjs
3. gart.config.json
4. package.json#gart

gart.config.js is the recommended format because repository credentials, environment-dependent URLs, and future advanced rules are easier to express in JavaScript.

Basic example:

module.exports = {
	srcDirs: ['skills'],
	managedSkillsDir: '.agents/skills',
	buildDir: '.gart',
	cacheDir: '.gart/cache',
	resolution: {
		repositories: [
			{type: 'mavenLocal', rootDir: 'C:/Users/me/.m2/repository'},
			{
				type: 'maven',
				url: 'http://localhost:5151/repository/garthub/',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:shared-skills:1.2.3'],
			exposedSkills: ['com.example.gart:ddd-base-skill:0.0.1'],
		},
	},
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'maven',
			url: 'http://localhost:5151/repository/garthub/',
			credentials: {
				usernameEnv: 'GART_REPO_USERNAME',
				passwordEnv: 'GART_REPO_PASSWORD',
			},
		},
	},
};

Publishing

Publish to a Remote Maven Repository

module.exports = {
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'maven',
			url: 'https://repo.example.com/maven-releases',
			credentials: {
				usernameEnv: 'GART_REPO_USERNAME',
				passwordEnv: 'GART_REPO_PASSWORD',
			},
		},
	},
};

Run:

npm run gart:publish

Publish to Local Maven

module.exports = {
	publishing: {
		coordinates: 'com.example.gart:my-skills:1.2.3',
		repository: {
			type: 'mavenLocal',
			rootDir: 'C:/Users/me/.m2/repository',
		},
	},
};

Artifact location:

~/.m2/repository/<group>/<artifact>/<version>/<artifact>-<version>-skills.zip

If you prefer, publishing coordinates may also be provided as:

• publishing.groupId
• publishing.artifactId
• publishing.version

When artifactId or version are omitted, Gart falls back to package.json.

Resolving Skill Dependencies

module.exports = {
	resolution: {
		repositories: [
			{type: 'mavenLocal', rootDir: 'C:/Users/me/.m2/repository'},
			{
				type: 'maven',
				url: 'https://repo.example.com/maven-releases',
				credentials: {
					usernameEnv: 'GART_REPO_USERNAME',
					passwordEnv: 'GART_REPO_PASSWORD',
				},
			},
		],
		dependencies: {
			skills: ['com.example.gart:shared-skills:1.2.3'],
			exposedSkills: ['com.example.gart:some-base-skill:0.0.1'],
		},
	},
};

• skills — local to the current project
• exposedSkills — also published transitively through the generated Maven POM

Resolved skills are unpacked into:

.agents/skills

Gart also writes a managed index file:

.agents/skills/gart.json

The index stores resolved dependencies, extracted file paths, checksums, and cleanup metadata.

Transitive Resolution

When exposedSkills are published, Gart generates Maven POM dependencies with:

• the same groupId, artifactId, and version
• classifier skills
• type zip

Consumers resolve those dependencies transitively during gart resolve.

At the moment, POM parsing supports explicit dependency coordinates and does not yet resolve Maven properties or dependencyManagement indirection.

Artifact Model

Gart uses Maven-compatible coordinates:

• groupId = publishing group
• artifactId = publishing artifact
• version = publishing version
• classifier = skills
• extension = zip

Example:

com/example/gart/my-project/1.2.3/my-project-1.2.3-skills.zip

The generated POM is published alongside the archive:

com/example/gart/my-project/1.2.3/my-project-1.2.3.pom

Safety Guarantees

Gart protects your workspace:

• does not overwrite user files silently
• removes only managed files
• fails on manual modifications of managed content
• prevents duplicate resource paths
• verifies checksums before deleting managed cache entries
• records checksums in build, publish, and managed index metadata

Build Boundary

Only local skill sources (skills/, srcDirs) are included in the built archive.

Resolved dependencies in .agents/skills are not repackaged automatically.

Summary

Gart introduces a missing layer in modern development:

A way to distribute knowledge together with code.

Instead of teaching developers how to use your library, you teach their AI once, and it applies the knowledge everywhere.

License

Package

@garthub/gart-npm is licensed under the Apache License 2.0.

Skills

All skills are distributed as separate artifacts and may use different licenses depending on their author.

Typical options include:

• open-source licenses
• source-available licenses
• commercial licenses

Always check the license of each skill dependency before use.