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

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. 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 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:

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

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

// 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, Dexter returns the project-specific definition:

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 – 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 – Parses individual SKILL.md files into structured skill objects.

• 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 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 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. There is no built-in support for environment variables or additional directory layers beyond built-in, user-wide, and project-specific scopes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}