# Settings.json Configuration Options That Control Skills Discovery in Prime Agent

> Master Prime Agent skills discovery by configuring settings.json. Learn how fields like 'skills' and 'enableSkillCommands' control skill loading and exposure.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-09-06

---

**The `skills`, `enableSkillCommands`, `enableBuiltinSkills`, and `bundledSkills` fields in [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) govern how Prime Agent discovers, loads, and exposes skills, while the `--no-skills` CLI flag overrides all discovery.**

PrimeIntellect-ai/prime-agent relies on a hierarchical JSON configuration system to determine which capabilities are available to the coding agent. By modifying specific keys in [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json), you control the discovery of custom skill modules, the exposure of built-in bundles, and whether capabilities appear as slash commands in the interface.

## Core Configuration Fields in Settings.json

The `SettingsManager` class in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts) parses four primary options that directly influence the discovery lifecycle. Each field maps to a specific line in the source where the value is read during initialization.

### The `skills` Array for Custom Discovery Paths

The **`skills`** array defines filesystem paths that the agent scans for user-defined skill modules. Each entry can point to a single file or a directory containing multiple `.js` or `.ts` skill definitions.

According to the source implementation at [line 90](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts#L90), the manager iterates over this array to locate loadable modules. If the array is empty (the default), the agent relies solely on built-in capabilities or CLI-provided overrides.

```json
{
  "skills": [
    "./my-custom-skills",
    "./project-specific/code-review.ts"
  ]
}

```

### Command Exposure via `enableSkillCommands`

The boolean field **`enableSkillCommands`** determines whether discovered skills are automatically registered as `/skill:<name>` slash commands. When set to `true` (default), each loaded skill becomes accessible via the command palette.

This behavior is controlled at [line 162](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts#L162) in [`settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings-manager.ts). Setting the value to `false` suppresses the command registration while still loading the skill code into the runtime for internal use.

```json
{
  "enableSkillCommands": false
}

```

### Built-in Bundle Control with `enableBuiltinSkills`

The **`enableBuiltinSkills`** boolean toggles the inclusion of the default "prime-agent" skill bundle. When `true` (default), the core discovery routine in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts) loads the bundled utilities. When `false`, the entire built-in set is omitted, leaving only user-defined skills from the `skills` array.

This check occurs at [line 164](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts#L164) of the settings manager.

```json
{
  "enableBuiltinSkills": false
}

```

### Granular Bundle Configuration via `bundledSkills`

For fine-grained control without disabling the entire built-in set, the **`bundledSkills`** object allows you to enable or disable individual bundled capabilities. This is parsed at [line 163](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts#L163), sitting between the global toggle and the final skill registration phase.

```json
{
  "bundledSkills": {
    "websearch": false,
    "file-analysis": true
  }
}

```

## CLI Override for Discovery

Regardless of [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) values, you can disable all skill discovery at runtime using the **`--no-skills`** (or `-ns`) flag. This override is defined in [`packages/coding-agent/src/cli/command-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/command-registry.ts) at [line 232](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli/command-registry.ts#L232) and takes precedence over any configuration file settings.

```bash
prime-agent --no-skills

# or

prime-agent -ns

```

## Practical Configuration Examples

### Global User Settings

Locate the global [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) at `~/.pi/agent/settings.json` to apply defaults across all projects:

```json
{
  "skills": [
    "~/agent-skills/utilities",
    "~/agent-skills/security-audit.ts"
  ],
  "enableSkillCommands": true,
  "enableBuiltinSkills": true,
  "bundledSkills": {
    "websearch": false
  }
}

```

### Project-Level Settings

Create a [`.prime/agent/settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.prime/agent/settings.json) file in your project root to override global options for a specific codebase:

```json
{
  "skills": [
    "./.prime/skills/project-helpers"
  ],
  "enableBuiltinSkills": false,
  "enableSkillCommands": true
}

```

### Disabling Discovery via CLI

When debugging or running in a restricted environment, bypass all skill loading:

```bash
prime-agent --no-skills --verbose

```

## Summary

- The **`skills`** array in [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) specifies filesystem paths for custom skill discovery.
- **`enableSkillCommands`** controls whether loaded skills appear as `/skill:<name>` slash commands.
- **`enableBuiltinSkills`** acts as a master switch for the default Prime Agent skill bundle.
- **`bundledSkills`** provides granular control over individual built-in capabilities.
- The **`--no-skills`** CLI flag overrides all configuration to disable discovery entirely.
- All options are parsed by `SettingsManager` in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts), with the final discovery logic implemented in [`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts).

## Frequently Asked Questions

### What happens if I set both `enableBuiltinSkills` and `skills` to empty/false?

If `enableBuiltinSkills` is `false` and the `skills` array is empty, the agent initializes with no available skills. The runtime will skip the discovery phase entirely, and only core agent capabilities without skill dependencies will function.

### Can I use environment variables instead of [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) for skill paths?

No. As implemented in [`settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings-manager.ts), the `skills` array is strictly read from the JSON configuration file. Path resolution relies on the [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) schema, and there is no environment variable interpolation for this specific field in the current source.

### Does the `--no-skills` flag affect the [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) file itself?

No. The `--no-skills` flag is a runtime override processed by the CLI argument parser in [`command-registry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/command-registry.ts). It prevents the discovery routine from executing but does not modify, delete, or persist any changes to your [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) file on disk.

### Where is the complete schema for [`settings.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings.json) documented?

The full schema and field descriptions are documented in [`packages/coding-agent/docs/settings.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/settings.md) within the repository. This file covers all configuration options beyond skill discovery, including logging levels and agent behavior thresholds.