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

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, 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, 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 supplies:

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

// 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 links these framework modules to their parent languages. For instance, 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.

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

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

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

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:

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 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) 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). 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 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, 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. 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.

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