# Dexter Skill Discovery Precedence Order: How Local Overrides Work in virattt/dexter

> Understand Dexter skill discovery precedence order. Learn how local overrides in virattt/dexter resolve conflicts by prioritizing project-specific skills over user-wide and built-in ones.

- Repository: [Virat Singh/dexter](https://github.com/virattt/dexter)
- Tags: internals
- Published: 2026-02-16

---

**Dexter resolves skill conflicts by processing built-in, user-wide, and project-specific directories in sequence, allowing project-level definitions to override user-wide and built-in skills with identical names.**

The Dexter skill discovery precedence order determines which skill definition takes effect when multiple sources define the same skill name. In the `virattt/dexter` repository, the registry implements a three-tier hierarchy that prioritizes local customization while maintaining stable defaults.

## The Three-Tier Skill Discovery Hierarchy

Dexter scans three distinct directories in a fixed sequence defined in [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts). The `SKILL_DIRECTORIES` constant establishes this priority chain:

1. **Built-in skills** – Located adjacent to the source code at `src/skills`. These ship with Dexter and provide default functionality.

2. **User-wide skills** – Stored in the current user's home directory under `~/.dexter/skills`. These definitions apply across all projects for that user.

3. **Project-specific skills** – Placed in a `.dexter/skills` folder at the root of the current working directory. These override both user and built-in definitions for the specific project context.

## How Precedence Resolution Works in Dexter

The `discoverSkills` function in [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts) processes the directory list sequentially. According to the implementation comments at lines 58-60, **later sources override earlier ones** when two skills share the same name.

This means the discovery routine maintains a single registry entry per skill name. When encountering a duplicate name during the scan, Dexter replaces the existing definition with the new one. Consequently, a project-level skill overrides a user-wide skill, which in turn overrides a built-in skill.

## Practical Example: Overriding the DCF Valuation Skill

Consider a scenario where you want to customize the **DCF Valuation** skill across different scopes. Dexter would resolve the following three definitions:

```ts
// 1. Built-in version (installed with Dexter)
// File: src/skills/dcf/SKILL.md
name: DCF Valuation
description: Built-in discount-cash-flow calculator

```

```ts
// 2. User-wide override
// File: ~/.dexter/skills/dcf/SKILL.md
name: DCF Valuation
description: User-customized DCF with extra assumptions

```

```ts
// 3. Project-specific override
// File: .dexter/skills/dcf/SKILL.md
name: DCF Valuation
description: Project-specific DCF that uses the company's latest metrics

```

When you call `getSkill('DCF Valuation')` from [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts), Dexter returns the project-specific definition:

```ts
import { getSkill } from '@/skills/registry';

const dcfSkill = getSkill('DCF Valuation');
console.log(dcfSkill?.description);
// Output: "Project-specific DCF that uses the company's latest metrics"

```

## Key Source Files and Implementation Details

The precedence logic resides in specific files within the `virattt/dexter` repository:

- **[`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts)** – Defines the `SKILL_DIRECTORIES` constant (lines 15-20) and implements the `discoverSkills` function with the "later overrides earlier" logic (lines 58-60).

- **[`src/skills/loader.ts`](https://github.com/virattt/dexter/blob/main/src/skills/loader.ts)** – Parses individual [`SKILL.md`](https://github.com/virattt/dexter/blob/main/SKILL.md) files into structured skill objects.

- **[`src/skills/types.ts`](https://github.com/virattt/dexter/blob/main/src/skills/types.ts)** – Contains TypeScript definitions for `Skill`, `SkillMetadata`, and `SkillSource` interfaces.

## Summary

- Dexter implements a **three-tier skill discovery precedence order**: built-in, user-wide, and project-specific directories.
- The registry processes directories sequentially, with **later definitions overriding earlier ones** when skill names collide.
- **Project-specific skills** (`.dexter/skills`) take highest precedence, enabling localized customization without affecting global defaults.
- The precedence logic is hardcoded in [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts) through the `SKILL_DIRECTORIES` array and the `discoverSkills` implementation.

## Frequently Asked Questions

### How does Dexter handle duplicate skill names across different directories?

Dexter resolves duplicates by keeping the last definition encountered during the discovery scan. Since [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts) processes built-in skills first, then user-wide skills, then project-specific skills, the project-level definition always wins when names match.

### Can I disable a built-in skill without overriding it completely?

Currently, Dexter does not support explicit skill disabling through configuration. To effectively disable a built-in skill, create a project-specific or user-wide skill with the same name that contains minimal or no-op functionality, effectively overriding the default implementation.

### Where should I place custom skills that need to be shared across multiple projects?

Place shared custom skills in the **user-wide directory** at `~/.dexter/skills`. Definitions stored here apply across all projects for your user account, while still allowing individual projects to override them with project-specific versions when necessary.

### Does Dexter support environment-specific skill overrides beyond the three tiers?

No, the `virattt/dexter` repository implements exactly three precedence tiers as defined in [`src/skills/registry.ts`](https://github.com/virattt/dexter/blob/main/src/skills/registry.ts). There is no built-in support for environment variables or additional directory layers beyond built-in, user-wide, and project-specific scopes.