# Structure of Language Definitions in skills/understand/languages/: A Complete Guide

> Explore the three-tier architecture of language definitions in Egonex AI's Understand Anything repo. Understand Markdown declarations TypeScript registries and framework modules.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: api-reference
- Published: 2026-06-23

---

**The language definitions in the Understand-Anything repository utilize a three-tier architecture combining Markdown skill declarations, TypeScript configuration registries, and optional framework augmentation modules.**

The `skills/understand/languages/` directory serves as the primary storage for language-specific knowledge in the Understand-Anything project. This structure enables the system to parse, analyze, and visualize code across multiple programming languages through a decoupled, extensible design that separates declarative skill definitions from imperative parsing logic.

## Overview of the Directory Architecture

The structure of language definitions spans two distinct locations within the `understand-anything-plugin` package:

1. **Markdown Skill Files** – Located in `understand-anything-plugin/skills/understand/languages/`, these files define the declarative capabilities and metadata for each supported language.
2. **TypeScript Registry & Configs** – Located in `understand-anything-plugin/packages/core/src/languages/`, these modules handle programmatic registration, parsing configurations, and framework-specific extensions.

## The Markdown Skill Files

Each language is represented by a dedicated Markdown file (e.g., [`python.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/python.md), [`javascript.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/javascript.md)) stored in `understand-anything-plugin/skills/understand/languages/`. These files contain a domain-specific language (DSL) that declares:

- Language identifiers and descriptions
- Supported file extensions
- Parsing rules and syntax highlighting preferences
- Sample code blocks for testing

The plugin engine consumes these Markdown files at runtime through the skill loader, treating them as the canonical source of truth for what the system knows about each language.

## The TypeScript Registry and Configuration

The core package provides the machinery that maps language IDs to executable configurations. The entry point is [`understand-anything-plugin/packages/core/src/languages/language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/languages/language-registry.ts), which exports a registry object that associates each language ID with a `Language` instance.

Supporting this registry is the `configs/` subdirectory containing language-specific parsing modules. For example, [`understand-anything-plugin/packages/core/src/languages/configs/python.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/languages/configs/python.ts) supplies:

- Tree-sitter grammar selectors
- File extension mappings
- Comment syntax delimiters
- Custom parser configurations

```typescript
// packages/core/src/languages/configs/python.ts
import { LanguageConfig } from './index';

export const pythonConfig: LanguageConfig = {
  parser: 'tree-sitter-python',
  extensions: ['.py', '.pyw'],
  comment: '#',
};

```

## Framework Augmentation Layer

Languages with popular frameworks include additional TypeScript modules in `understand-anything-plugin/packages/core/src/languages/frameworks/`. These helpers extend base language definitions with domain-specific analysis capabilities.

The [`understand-anything-plugin/packages/core/src/languages/framework-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/languages/framework-registry.ts) links these framework modules to their parent languages. For instance, [`frameworks/react.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/frameworks/react.ts) defines component detection patterns that layer on top of the base JavaScript definition, enabling the system to识别 component hierarchies and routing tables.

```typescript
// packages/core/src/languages/frameworks/react.ts
export const reactFramework = {
  parentLanguage: 'javascript',
  componentPatterns: [/function\s+\w+\s*\(.*\)\s*\{[\s\S]*?return\s+\(/, /class\s+\w+\s+extends\s+React\.Component/],
  hooks: ['useState', 'useEffect', 'useContext']
};

```

## How the Layers Work Together

The system initializes language support through a four-stage pipeline:

1. **Discovery** – The [`language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/language-registry.ts) automatically discovers all available languages by scanning the `languages/` directory and loading exported modules.
2. **Parsing** – When analyzing a file, the registry retrieves the associated `LanguageConfig` from the `configs/` directory to determine which tree-sitter grammar and file extensions apply.
3. **Framework Merging** – If framework helpers exist for the detected language, the [`framework-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/framework-registry.ts) merges these capabilities into the base language definition.
4. **Execution** – The assembled language definition is passed to the analysis engine, which generates the knowledge graph and visualization data.

## Adding a New Language Definition

To add support for a new language such as Elixir, create three artifacts following the established structure:

First, create the Markdown skill file at [`understand-anything-plugin/skills/understand/languages/elixir.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/languages/elixir.md):

```markdown

# Elixir

## Overview

Elixir is a functional, concurrent language built on the BEAM VM.

## File extensions

- `.ex`
- `.exs`

## Configuration

{
  "languageId": "elixir",
  "description": "Elixir source files",
  "extensions": [".ex", ".exs"]
}

```

Next, add the optional TypeScript configuration at [`packages/core/src/languages/configs/elixir.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/languages/configs/elixir.ts):

```typescript
import { LanguageConfig } from './index';

export const elixirConfig: LanguageConfig = {
  parser: 'tree-sitter-elixir',
  extensions: ['.ex', '.exs', '.eex'],
  comment: '#',
};

```

Finally, the registry automatically picks up the new language through the `export * from './languages/*'` pattern used in [`language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/language-registry.ts), requiring no manual registration beyond creating the files.

## Accessing Language Definitions Programmatically

The core package exposes helpers to retrieve fully assembled language definitions at runtime:

```typescript
import { getLanguage } from '@understand-anything/core/languages';

async function analyzeLanguage(id: string) {
  const lang = await getLanguage(id);
  console.log(`Language: ${lang.id}`);
  console.log(`Extensions: ${lang.extensions.join(', ')}`);
  console.log(`Parser: ${lang.config.parser}`);
}

// Retrieve Python definition
analyzeLanguage('python');

```

For framework-specific analysis, access the framework registry:

```typescript
import { getFramework } from '@understand-anything/core/languages/frameworks';

async function loadReactSupport() {
  const react = await getFramework('react');
  console.log('Component patterns:', react.componentPatterns);
  console.log('Supported hooks:', react.hooks);
}

```

The `getLanguage` helper automatically merges the Markdown skill, TypeScript config, and any associated framework definitions into a single typed `Language` object.

## Summary

- **Markdown skill files** in `skills/understand/languages/` provide the declarative foundation for each language supported by the system.
- **TypeScript registries** in `packages/core/src/languages/` handle the imperative logic of parsing, file extension mapping, and runtime configuration.
- **Framework helpers** in `packages/core/src/languages/frameworks/` extend base languages with domain-specific analysis capabilities for popular frameworks.
- **Automatic discovery** via [`language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/language-registry.ts) means adding support requires only creating the appropriate files, with no manual registration needed.
- **Layered architecture** separates concerns between declaration (Markdown), configuration (TypeScript), and specialization (Frameworks), enabling maintainable extensibility.

## Frequently Asked Questions

### What file format are language definitions stored in?

Language definitions use a hybrid format. The primary declarations reside in Markdown files (e.g., [`python.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/python.md)) located in `skills/understand/languages/`, containing a DSL that describes the language's capabilities. Supplementary TypeScript files in `packages/core/src/languages/configs/` provide the executable parsing logic and grammar configurations.

### How do I add support for a new programming language?

Create a new Markdown file in `understand-anything-plugin/skills/understand/languages/` named after the language (e.g., [`rust.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/rust.md)). Include the language metadata, file extensions, and description in the Markdown DSL. Optionally, add a TypeScript configuration file in `packages/core/src/languages/configs/` to specify the tree-sitter parser and comment syntax. The [`language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/language-registry.ts) automatically discovers and loads the new definition.

### What is the purpose of the framework registry?

The framework registry, located at [`packages/core/src/languages/framework-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/languages/framework-registry.ts), manages the relationship between base languages and their framework-specific extensions. It allows the system to layer additional analysis capabilities—such as React component detection or Spring Boot route mapping—on top of standard language definitions without modifying the core language files.

### Where is the central language registry located?

The central language registry is implemented in [`understand-anything-plugin/packages/core/src/languages/language-registry.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/languages/language-registry.ts). This file exports the main registry object that maps language identifiers (e.g., `python`, `typescript`) to their corresponding `Language` objects, coordinating the loading of Markdown skills, TypeScript configs, and framework helpers.