skill-ls/AGENTS.md

Project Overview: skillls

skillls is a Language Server Protocol (LSP) implementation for the Skill language (specifically targeting .il and .ocn files). It provides essential IDE features to enhance the development experience, such as error detection, structural navigation, and intelligent code hints.

Core Capabilities

The server implements several key LSP features:

• Diagnostics: Automatically detects syntax errors, specifically focusing on parenthesis mismatches (too many opening or closing parentheses), and reports them with precise line/column information to the editor.
• Document Symbols: Parses the file structure to generate a hierarchy of scopes (nodes). This enables editors to provide an "Outline" or "Symbol Tree" view for navigating functions, variables, and namespaces.
• Inlay Hints: Provides inline metadata at specific code locations, allowing the editor to display additional context directly within the source text.
• Workspace Initialization: Upon connecting, the server scans the workspace root for relevant .il and .ocn files, building an initial representation of the project's scopes.

Architecture & Implementation

Parsing Logic

The project uses a multi-layered approach to understand the Skill language:

1. Content Cleaning: A pre-processing step identifies and handles comments (;) and strings ("...") to ensure parsing is not misled by ignored text.
2. Structural Analysis: The server identifies "scope starters" using regular expressions and manual parenthesis tracking to determine the boundaries of functions or namespaces.
3. Hierarchy Building: Once individual nodes are identified, the server builds a parent-child tree structure based on the nesting level of parentheses.
4. Symbol Extraction: Within each scope, the parser identifies local variables and symbols to populate the DocumentSymbol list.

Key Components

• skillls/main.py: The entry point of the LSP server. It implements the LanguageServer class and contains the handlers for LSP lifecycle events (initialize, didOpen, didChange, etc.) and feature requests (inlayHint, documentSymbol).
• skillls/checker.py: Contains the logic for syntactic validation, specifically the algorithm for detecting unbalanced parentheses.
• skillls/helpers.py: Provides the heavy lifting for text processing, including the content cleaning state machine and the recursive logic for building the node hierarchy.
• skillls/types.py: Defines the internal data models (e.g., Node, URI) used across the project.

Technical Stack

• Language: Python 3.11+
• LSP Framework: pygls (Python Language Server)
• Parsing Utilities: parsimonious (PEG parser), tree-sitter (for structural tree analysis).
• Formatting & Tooling: rich (terminal output), black, ruff, mypy.