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/parser.py: The new Tree-sitter based parser for syntax tree traversal and symbol extraction.
• skillls/types.py: Defines the internal data models (e.g., Node, URI) used across the project.

Roadmap & Engineering Planning

For details on identified technical debt, fragilities, and the long-term architectural hardening strategy, refer to PLAN.md.

Technical Stack

• Language: Python 3.11+
• Package Management: uv
• LSP Framework: pygls (Python Language Server)
• Parsing Utilities: tree-sitter (for structural tree analysis).
• Formatting & Tooling: rich (terminal output), ruff, mypy, pytest.