lcode-cli 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

lcode/__init__.py

@@ -1,3 +1,3 @@
 """lcode — a local-first terminal coding agent powered by open-weight models via Ollama."""
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"

lcode/agent.py

@@ -21,7 +21,7 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, limits, planning, sessions, subagents, vision, web
+from lcode import catalog, extensions, limits, planning, sessions, subagents, vision, web
 from lcode import memory as memory_notes
 from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
@@ -78,7 +78,7 @@ SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent runni
 
 # Top-level layout of the working directory
 {tree}
-{web}{agents}{project}{notes}"""
+{web}{agents}{skills}{project}{notes}"""
 
 WEB_PROMPT = """
 # Web access
@@ -171,6 +171,8 @@ class Settings:
     vision_model: str = "auto"  # auto, off or an Ollama model that can see images
     memory: str = "off"  # off, ask or auto: notes that carry over to later sessions (lcode.memory)
     subagents: bool = False  # the agent tool (lcode.subagents)
+    trust_project: bool = False  # use the repository's own commands, skills and agents (lcode.extensions)
+    skills: str = "off"  # all, lcode (only lcode's own skill folders) or off
     max_parallel_agents: int = 1
 
 
@@ -200,6 +202,8 @@ class Agent:
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
         self.agent_runs: list[subagents.Record] = []  # subagents run in this session, for /agents
         self.plan = ""  # the plan the user approved; kept through compaction
+        self._extensions: tuple[Path, extensions.Extensions] | None = None
+        self.skills_loaded: set[str] = set()  # skills whose instructions are in the conversation
         # Set on subagents (see lcode.subagents):
         self.allowed_tools: set[str] | None = None  # None: every tool
         self.read_only = False  # only read-only shell commands
@@ -236,8 +240,15 @@ class Agent:
             notes=self.memory().prompt(self.settings.context) if self.settings.memory != "off" else "",
             web=self.web_prompt(),
             agents=self.agents_prompt(),
+            skills=extensions.skills_prompt(self.extensions().skills, self.settings.context),
         )
 
+    def extensions(self) -> extensions.Extensions:
+        """Custom commands and skills for the current folder (a repository's only once approved)."""
+        if self._extensions is None or self._extensions[0] != self.cwd:
+            self._extensions = (self.cwd, extensions.load(self.cwd, self.settings.trust_project, self.settings.skills))
+        return self._extensions[1]
+
     def agents_prompt(self) -> str:
         if not self.settings.subagents:
             return ""
@@ -252,7 +263,7 @@ class Agent:
     def agent_types(self) -> dict[str, subagents.AgentType]:
         """Built-in and custom agent types for the current folder."""
         if self._agent_types is None or self._agent_types[0] != self.cwd:
-            types, problems = subagents.load_types(self.cwd)
+            types, problems = subagents.load_types(self.cwd, self.settings.trust_project)
             self._agent_types = (self.cwd, types, problems)
         return self._agent_types[1]
 
@@ -290,6 +301,8 @@ class Agent:
             schemas.append(subagents.schema(self.agent_types(), self.settings.max_parallel_agents))
         if self.planning():
             schemas.append(PRESENT_PLAN_SCHEMA)
+        if self.extensions().skills:
+            schemas.append(extensions.schema(self.extensions().skills))
         if self.mcp:
             schemas += self.mcp.schemas(self.settings.context)
         if self.allowed_tools is not None:
@@ -409,6 +422,7 @@ class Agent:
 
     def new_session(self) -> None:
         self.reset()
+        self.skills_loaded.clear()
         self.session_id = self.new_session_id()
         self.session_name = ""
         self.session_title = ""
@@ -606,6 +620,8 @@ class Agent:
             return f"list_dir({args.get('path', '.')})"
         if name == "memory":
             return f"memory({' '.join(str(args.get(k) or '') for k in ('action', 'name')).strip()})"
+        if name == "skill":
+            return f"skill({args.get('name', '')})"
         if name == "agent":
             return f"agent({args.get('type', '')}: {args.get('description') or str(args.get('task', ''))[:50]})"
         if name == "bash":
@@ -787,6 +803,12 @@ class Agent:
         ]
         if self.plan:  # the approved plan stays word for word
             self.messages[1]["content"] += f"\n\n[The plan the user approved; keep following it]\n\n{self.plan}"
+        if self.skills_loaded:  # their instructions were in the old messages: load them again when needed
+            names = ", ".join(sorted(self.skills_loaded))
+            self.messages[1]["content"] += (
+                f"\n\n[Skills in use before the summary: {names}. Load them again with the skill tool if you still need them.]"
+            )
+            self.skills_loaded.clear()
         self.ctx_used = sum(len(m["content"]) for m in self.messages) // 3
         self.reflected = len(self.messages)
         self.console.print(Panel(Markdown(summary), title="Compacted summary", border_style="blue"))

lcode/cli.py

@@ -367,6 +367,20 @@ def cmd_doctor(args) -> None:
             line("", f"{n} × {slots[1]} context may not fit in memory here; {slots[0]} would", None)
         for problem in problems:
             line("", problem, None)
+    from lcode import extensions
+
+    project_state = extensions.status(Path.cwd())
+    ext = extensions.load(Path.cwd(), include_project=project_state == "approved", skills_from=cfg["skills"])
+    found = f"{len(ext.commands)} command(s), {len(ext.skills)} skill(s)"
+    note = {
+        "none": "",
+        "approved": " · this repository's are approved",
+        "new": " · this repository brings its own: approve them when lcode asks",
+        "changed": " · this repository's changed since you approved them: lcode asks again",
+    }[project_state]
+    line("Extras", found + note, None if project_state in ("new", "changed") else True)
+    for problem in ext.problems:
+        line("", problem, None)
     if cfg["memory"] == "off":
         line("Memory", "off (lcode config set memory ask)", True)
     else:
@@ -528,6 +542,9 @@ def cmd_chat(args) -> None:
             num_batch = spec.num_batch
         else:  # the tuned batch size assumes the text-only variant; the vision projector needs that VRAM
             console.print(f"[dim]Tip: run `lcode setup {spec.key}` once to create the faster text-only variant.[/]")
+    from lcode import extensions
+
+    trust_project = extensions.trust_project(cwd, console, interactive=not args.prompt)
     settings = Settings(
         model=model,
         context=context,
@@ -547,6 +564,8 @@ def cmd_chat(args) -> None:
         memory="off" if args.no_memory else cfg["memory"],
         subagents=cfg["subagents"],
         max_parallel_agents=cfg["max_parallel_agents"],
+        trust_project=trust_project,
+        skills=cfg["skills"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
     agent.interactive = not args.prompt

lcode/config.py

@@ -27,6 +27,7 @@ SEARCH_BACKENDS = ("auto", "ollama", "brave", "tavily", "searxng")
 MCP_TOOL_MODES = ("auto", "direct", "search")
 SANDBOX_ENGINES = ("off", "docker", "podman")
 MEMORY_MODES = ("off", "ask", "auto")
+SKILL_SOURCES = ("all", "lcode", "off")
 
 # key -> (default, type, help)
 SETTINGS: dict[str, tuple[object, type, str]] = {
@@ -47,6 +48,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "vision_model": ("auto", str, "model that looks at images: auto | off | an Ollama model with vision"),
     "mcp_tools": ("auto", str, "how MCP tools reach the model: auto | direct | search (on demand, saves context)"),
     "memory": ("ask", str, "notes that carry over to later sessions: off | ask (confirm each) | auto"),
+    "skills": ("all", str, "skills to offer the model: all (also other agents' folders) | lcode | off"),
     "subagents": (True, bool, "let the model hand tasks to subagents that have their own context"),
     "max_parallel_agents": (1, int, "subagents that may run at the same time (more needs OLLAMA_NUM_PARALLEL)"),
 }
@@ -120,6 +122,10 @@ def coerce(key: str, value: object) -> object:
         if value not in MEMORY_MODES:
             raise ConfigError(f"memory must be one of {', '.join(MEMORY_MODES)}")
         return value
+    if key == "skills" and str(value).lower() not in SKILL_SOURCES:
+        raise ConfigError(f"skills must be one of {', '.join(SKILL_SOURCES)}")
+    if key == "skills":
+        return str(value).lower()
     if key == "mcp_tools" and value not in MCP_TOOL_MODES:
         raise ConfigError(f"mcp_tools must be one of {', '.join(MCP_TOOL_MODES)}")
     if key == "search_backend" and value not in SEARCH_BACKENDS:

lcode/extensions.py

@@ -0,0 +1,405 @@
+"""Custom slash commands and skills, and the approval of those a repository brings.
+
+Commands are prompt templates: `.lcode/commands/<name>.md` in a repository or
+`~/.config/lcode/commands/<name>.md`, run as `/name args`. `$ARGUMENTS` in the template becomes
+everything after the name, `$1`…`$9` single words. An optional frontmatter gives a description,
+an argument hint for /help and the tools the model may use for that request.
+
+Skills follow the Agent Skills format (https://agentskills.io): a folder with a SKILL.md
+(frontmatter with name and description, then instructions) and any scripts or reference files next
+to it. lcode looks in `.lcode/skills/`, `.agents/skills/` and `.claude/skills/` of the repository and
+the same places in the user's home (`~/.config/lcode/skills/` for lcode's own). Only the names and
+descriptions are in the system prompt; the instructions load when the model calls the skill tool for
+a task that matches, or when the user runs `/name`. Bundled files are listed, not read, until needed.
+
+A repository's commands, skills and agents can steer the model and bring scripts it may run, so
+lcode asks before using them the first time, and again whenever they change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.markup import escape
+
+from lcode import config
+from lcode.checkpoints import work_tree_for
+from lcode.frontmatter import split
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from lcode.agent import Agent
+
+SKILL_FOLDERS = (".lcode/skills", ".agents/skills", ".claude/skills")  # in a repository, first found wins
+PROJECT_FOLDERS = (".lcode/commands", ".lcode/agents", *SKILL_FOLDERS)  # what needs approval
+MAX_SKILLS_PROMPT = 6000  # characters of skill descriptions in the system prompt (~2K tokens)
+MAX_DESCRIPTION = 300  # characters of one skill's description in the system prompt
+MIN_DESCRIPTION = 40  # with many skills, descriptions are cut down to this rather than skills left out
+MAX_RESOURCES = 50
+MAX_FILES = 2000  # files looked at when fingerprinting a repository's extensions
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv"}
+
+SKILLS_PROMPT = """
+# Skills
+Skills are instructions for specific kinds of tasks. When a task matches a skill's description, call the skill tool with its name first, then follow the instructions it returns. Paths in a skill are relative to its folder; use the absolute paths it gives.
+{catalog}
+"""
+
+
+class ExtensionError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    description: str
+    template: str
+    path: Path
+    scope: str  # project | user
+    argument_hint: str = ""
+    tools: frozenset[str] | None = None
+
+    def render(self, args: str) -> str:
+        """The request: the template with $ARGUMENTS and $1…$9 filled in."""
+        words = args.split()
+        text = self.template
+        used = "$ARGUMENTS" in text or re.search(r"\$[1-9]", text)
+        text = text.replace("$ARGUMENTS", args)
+        text = re.sub(r"\$([1-9])", lambda m: words[int(m.group(1)) - 1] if int(m.group(1)) <= len(words) else "", text)
+        if args and not used:
+            text = f"{text.rstrip()}\n\n{args}"
+        return text.strip()
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    path: Path  # the SKILL.md
+    scope: str
+
+    @property
+    def folder(self) -> Path:
+        return self.path.parent
+
+    def instructions(self) -> str:
+        parts = split(self.path.read_text(errors="replace"))
+        return (parts[1] if parts else self.path.read_text(errors="replace")).strip()
+
+    def resources(self) -> list[str]:
+        found = []
+        for root, dirs, files in os.walk(self.folder):
+            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
+            for name in sorted(files):
+                path = Path(root) / name
+                if path != self.path:
+                    found.append(path.relative_to(self.folder).as_posix())
+                if len(found) > MAX_RESOURCES:
+                    return found
+        return found
+
+
+# ----------------------------------------------------------------------------- loading
+
+
+def user_skill_folders(which: str = "all") -> list[Path]:
+    home = Path.home()
+    other_agents = [home / ".agents" / "skills", home / ".claude" / "skills"] if which == "all" else []
+    return [config.CONFIG_DIR / "skills", *other_agents]
+
+
+def load_commands(cwd: Path, include_project: bool) -> tuple[dict[str, Command], list[str]]:
+    folders = [(config.CONFIG_DIR / "commands", "user")]
+    if include_project:
+        folders.append((work_tree_for(cwd) / ".lcode" / "commands", "project"))
+    commands: dict[str, Command] = {}
+    problems = []
+    for folder, scope in folders:  # the repository's override the user's
+        for f in sorted(folder.glob("*.md")) if folder.is_dir() else []:
+            try:
+                commands[f.stem] = parse_command(f, scope)
+            except (ExtensionError, OSError) as e:
+                problems.append(f"{f}: {e}")
+    return commands, problems
+
+
+def parse_command(path: Path, scope: str) -> Command:
+    from lcode.tools import TOOL_NAMES
+
+    name = path.stem
+    if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name):
+        raise ExtensionError("the file name must be lowercase letters, digits, - or _")
+    text = path.read_text(errors="replace")
+    fields, body = split(text) or ({}, text)
+    if not body.strip():
+        raise ExtensionError("the command has no prompt")
+    tools = None
+    listed = fields.get("allowed-tools") or fields.get("tools")
+    if listed:
+        tools = frozenset(t for t in re.split(r"[,\s]+", listed.strip("[]")) if t)
+        unknown = tools - TOOL_NAMES
+        if unknown:
+            raise ExtensionError(
+                f"unknown tools: {', '.join(sorted(unknown))} (lcode's tools: {', '.join(sorted(TOOL_NAMES))})"
+            )
+    first = next((line.strip() for line in body.strip().splitlines() if line.strip()), "")
+    return Command(
+        name=name,
+        description=" ".join(fields.get("description", "").split()) or first[:80],
+        template=body.strip(),
+        path=path,
+        scope=scope,
+        argument_hint=fields.get("argument-hint", ""),
+        tools=tools,
+    )
+
+
+def load_skills(cwd: Path, include_project: bool, which: str = "all") -> tuple[dict[str, Skill], list[str]]:
+    """Skills from lcode's folders and, with `which` = all, the folders other agents share."""
+    if which == "off":
+        return {}, []
+    places = [(folder, "user") for folder in user_skill_folders(which)]
+    if include_project:
+        root = work_tree_for(cwd)
+        places += [(root / folder, "project") for folder in (SKILL_FOLDERS if which == "all" else SKILL_FOLDERS[:1])]
+    skills: dict[str, Skill] = {}
+    problems = []
+    for folder, scope in places:
+        for skill_file in sorted(folder.glob("*/SKILL.md")) if folder.is_dir() else []:
+            try:
+                skill = parse_skill(skill_file, scope)
+            except (ExtensionError, OSError) as e:
+                problems.append(f"{skill_file}: {e}")
+                continue
+            existing = skills.get(skill.name)
+            if existing and existing.scope == scope:
+                if not same_file(existing.path, skill_file):  # the same skill installed twice is fine
+                    problems.append(f"{skill_file}: skipped, {existing.path} has the same name")
+                continue
+            skills[skill.name] = skill  # a repository's skill replaces the user's
+    return skills, problems
+
+
+def same_file(a: Path, b: Path) -> bool:
+    try:
+        return a.resolve() == b.resolve() or a.read_bytes() == b.read_bytes()
+    except OSError:
+        return False
+
+
+def parse_skill(path: Path, scope: str) -> Skill:
+    parts = split(path.read_text(errors="replace"))
+    if not parts:
+        raise ExtensionError("SKILL.md needs a frontmatter with a name and a description")
+    fields = parts[0]
+    description = " ".join(fields.get("description", "").split())
+    if not description:
+        raise ExtensionError("the frontmatter needs a description")
+    # Lenient, like other clients: a name that breaks the format rules still works, as the folder name.
+    name = fields.get("name", "").strip() or path.parent.name
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name) or len(name) > 64:
+        name = path.parent.name
+    return Skill(name=name, description=description, path=path, scope=scope)
+
+
+# ----------------------------------------------------------------------------- using skills
+
+
+def skills_prompt(skills: dict[str, Skill], context: int = 262144) -> str:
+    """The skill catalog for the system prompt: within ~5% of the context window, every skill listed
+    (descriptions are shortened first), and only then cut off."""
+    if not skills:
+        return ""
+    budget = min(MAX_SKILLS_PROMPT, context * 3 // 20)
+    room = budget // len(skills) - 6
+    lines, used = [], 0
+    for skill in skills.values():
+        limit = max(MIN_DESCRIPTION, min(MAX_DESCRIPTION, room - len(skill.name)))
+        description = skill.description
+        if len(description) > limit:
+            description = description[: limit - 1].rstrip() + "…"
+        line = f"- {skill.name}: {description}"
+        if used + len(line) > budget:
+            lines.append(f"- … and {len(skills) - len(lines)} more (the skill tool lists them all)")
+            break
+        lines.append(line)
+        used += len(line) + 1
+    return SKILLS_PROMPT.format(catalog="\n".join(lines))
+
+
+def schema(skills: dict[str, Skill]) -> dict:
+    from lcode.tools import _fn
+
+    return _fn(
+        "skill",
+        "Load a skill's instructions when the task matches its description (see Skills). Returns the "
+        "instructions, the skill's folder and the files in it.",
+        {"name": {"type": "string", "enum": sorted(skills)}},
+        ["name"],
+    )
+
+
+def content(skill: Skill) -> str:
+    """What the model gets when a skill is activated: instructions, folder and bundled files."""
+    files = skill.resources()
+    listing = "\n".join(f"  {f}" for f in files[:MAX_RESOURCES])
+    if len(files) > MAX_RESOURCES:
+        listing += "\n  … (more files; list the folder to see them)"
+    return (
+        f'<skill_content name="{skill.name}">\n{skill.instructions()}\n\n'
+        f"Skill folder: {skill.folder}\nRelative paths in this skill are relative to that folder: use "
+        "absolute paths in tool calls.\n"
+        + (f"<skill_resources>\n{listing}\n</skill_resources>\n" if files else "")
+        + "</skill_content>"
+    )
+
+
+def activate(agent: Agent, name: str) -> str:
+    skills = agent.extensions().skills
+    if name not in skills:
+        return f"Error: no skill {name!r}. Skills: {', '.join(sorted(skills)) or 'none'}"
+    if name in agent.skills_loaded:
+        return f"The {name} skill's instructions are already loaded above; follow them."
+    try:
+        text = content(skills[name])
+    except OSError as e:
+        return f"Error: can't read the {name} skill: {e}"
+    agent.skills_loaded.add(name)
+    return text
+
+
+# ----------------------------------------------------------------------------- approving a repository's extensions
+
+
+def approvals_path() -> Path:
+    return config.STATE_DIR / "extensions-approved.json"
+
+
+def project_files(cwd: Path) -> tuple[Path, list[Path]]:
+    """The repository's root and the files of its commands, skills and agents."""
+    root = work_tree_for(cwd)
+    files: list[Path] = []
+    for folder in PROJECT_FOLDERS:
+        base = root / folder
+        if not base.is_dir():
+            continue
+        for current, dirs, names in os.walk(base):
+            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
+            files += [Path(current) / n for n in sorted(names)]
+            if len(files) >= MAX_FILES:
+                return root, files[:MAX_FILES]
+    return root, files
+
+
+def fingerprint(root: Path, files: list[Path]) -> str:
+    digest = hashlib.sha256()
+    for f in files:
+        digest.update(f.relative_to(root).as_posix().encode() + b"\0")
+        try:
+            digest.update(hashlib.sha256(f.read_bytes()).digest())
+        except OSError:
+            digest.update(b"?")
+    return digest.hexdigest()
+
+
+def _approved() -> dict:
+    try:
+        data = json.loads(approvals_path().read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def status(cwd: Path) -> str:
+    """none (the repository brings nothing), approved, new or changed."""
+    root, files = project_files(cwd)
+    if not files:
+        return "none"
+    seen = _approved().get(str(root))
+    if seen is None:
+        return "new"
+    return "approved" if seen == fingerprint(root, files) else "changed"
+
+
+def approve(cwd: Path) -> None:
+    root, files = project_files(cwd)
+    data = _approved()
+    data[str(root)] = fingerprint(root, files)
+    approvals_path().parent.mkdir(parents=True, exist_ok=True)
+    approvals_path().write_text(json.dumps(data, indent=2))
+
+
+def describe(cwd: Path) -> list[str]:
+    """What the repository brings, one line per kind."""
+    from lcode.subagents import parse_agent
+
+    root = work_tree_for(cwd)
+    commands, _ = load_commands(cwd, include_project=True)
+    skills, _ = load_skills(cwd, include_project=True)
+    agents = []
+    for f in sorted((root / ".lcode" / "agents").glob("*.md")):
+        try:
+            agents.append(parse_agent(f.read_text(errors="replace"), f.stem, str(f)).name)
+        except (ValueError, OSError):
+            continue
+    lines = []
+    project_commands = [f"/{c.name}" for c in commands.values() if c.scope == "project"]
+    project_skills = [s.name for s in skills.values() if s.scope == "project"]
+    if project_commands:
+        lines.append(f"commands: {', '.join(project_commands)}")
+    if project_skills:
+        lines.append(f"skills: {', '.join(project_skills)}")
+    if agents:
+        lines.append(f"agents: {', '.join(agents)}")
+    return lines
+
+
+def trust_project(cwd: Path, console: Console, interactive: bool) -> bool:
+    """Whether to use the repository's commands, skills and agents; asks the first time."""
+    state = status(cwd)
+    if state in ("none", "approved"):
+        return state == "approved"
+    root = work_tree_for(cwd)
+    if not interactive:
+        console.print(
+            f"[dim]Not using the commands, skills and agents in {escape(str(root))} until you approve them in a session.[/]"
+        )
+        return False
+    changed = " [yellow](changed since you approved them)[/]" if state == "changed" else ""
+    console.print(f"This repository brings its own commands, skills or agents{changed}:")
+    for line in describe(cwd) or ["(files in " + ", ".join(PROJECT_FOLDERS) + ")"]:
+        console.print(f"  {escape(line)}")
+    console.print(
+        "[dim]They can steer the model and include scripts it may run (commands still ask first, unless "
+        "you allow them).[/]"
+    )
+    try:
+        answer = input("  Use them? [y/N] ").strip().lower()
+    except EOFError:
+        answer = ""
+    if answer in ("y", "yes"):
+        approve(cwd)
+        return True
+    console.print("[dim]Not using them in this session. You'll be asked again next time.[/]")
+    return False
+
+
+@dataclass
+class Extensions:
+    commands: dict[str, Command]
+    skills: dict[str, Skill]
+    problems: list[str]
+
+
+def load(cwd: Path, include_project: bool, skills_from: str = "all") -> Extensions:
+    commands, command_problems = load_commands(cwd, include_project)
+    skills, skill_problems = load_skills(cwd, include_project, skills_from)
+    return Extensions(commands, skills, command_problems + skill_problems)

lcode/frontmatter.py

@@ -0,0 +1,62 @@
+"""The `---` header of markdown files: memory notes, agents, commands and skills.
+
+A small, lenient subset of YAML, enough for these headers without a YAML dependency:
+`key: value` lines, quoted values, block scalars (`key: |` and `key: >`, with indented lines below),
+and nested maps or lists (kept as raw text). Skills written for other agents sometimes have values
+that strict YAML rejects, such as an unquoted colon in a description; those are read as plain text.
+"""
+
+from __future__ import annotations
+
+import re
+
+BLOCK = re.compile(r"^[|>][+-]?$")
+
+
+def split(text: str) -> tuple[dict[str, str], str] | None:
+    """The header fields and the body after them, or None when the text has no header."""
+    m = re.match(r"?---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|$)(.*)", text, re.S)
+    if not m:
+        return None
+    return parse(m.group(1)), m.group(2)
+
+
+def parse(header: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    lines = header.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        i += 1
+        if not line.strip() or line.lstrip().startswith("#") or line[:1].isspace():
+            continue
+        key, sep, value = line.partition(":")
+        if not sep:
+            continue
+        key, value = key.strip(), value.strip()
+        nested = []
+        while i < len(lines) and (not lines[i].strip() or lines[i][:1].isspace()):
+            nested.append(lines[i])
+            i += 1
+        while nested and not nested[-1].strip():
+            nested.pop()
+        if BLOCK.match(value):
+            indent = min((len(n) - len(n.lstrip()) for n in nested if n.strip()), default=0)
+            body = [n[indent:] for n in nested]
+            if value.startswith(">"):
+                value = re.sub(r"(?<!\n)\n(?!\n)", " ", "\n".join(body)).strip()
+            else:
+                value = "\n".join(body).rstrip()
+        elif not value and nested:
+            value = "\n".join(nested)  # a nested map or list, kept as text
+        elif nested:
+            value = " ".join([value, *(n.strip() for n in nested)]).strip()  # a plain value over several lines
+        fields[key] = unquote(value)
+    return fields
+
+
+def unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+        inner = value[1:-1]
+        return inner.replace("''", "'") if value[0] == "'" else inner.replace('\\"', '"').replace("\\n", "\n")
+    return value

lcode/memory.py

@@ -39,6 +39,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from lcode import config
+from lcode.frontmatter import split as frontmatter
 
 if TYPE_CHECKING:
     from lcode.agent import Agent
@@ -186,19 +187,6 @@ def project_dir(cwd: Path) -> Path:
     return memory_dir() / "projects" / f"{slugify(name, 40) or 'folder'}-{key}"
 
 
-def frontmatter(text: str) -> tuple[dict[str, str], str] | None:
-    """The `key: value` header between --- lines, and the body after it (None without a header)."""
-    m = re.match(r"---\r?\n(.*?)\r?\n---\r?\n?(.*)", text, re.S)
-    if not m:
-        return None
-    fields = {}
-    for line in m.group(1).splitlines():
-        key, sep, value = line.partition(":")
-        if sep:
-            fields[key.strip()] = value.strip()
-    return fields, m.group(2)
-
-
 def parse(text: str, scope: str, path: Path | None = None) -> Note | None:
     split = frontmatter(text)
     if not split:

lcode/planning.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:
 PLAN_MODE_TOOLS = frozenset(
     {
         "read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write",
-        "agent", "memory", "present_plan", "mcp_find_tools",
+        "agent", "memory", "present_plan", "mcp_find_tools", "skill",
     }
 )  # fmt: skip
 

lcode/repl.py

@@ -25,7 +25,7 @@ from rich.rule import Rule
 from rich.table import Table
 from rich.text import Text
 
-from lcode import __version__, catalog, limits, sessions, web
+from lcode import __version__, catalog, extensions, limits, sessions, web
 from lcode import memory as memory_notes
 from lcode.agent import AUTO_COMPACT_RATIO, INIT_PROMPT, Agent
 from lcode.catalog import MIN_USEFUL_CONTEXT
@@ -73,7 +73,7 @@ class InputCompleter(Completer):
     def get_completions(self, document, complete_event):
         text = document.text_before_cursor
         if text.startswith("/") and " " not in text:
-            for cmd, desc in COMMANDS.items():
+            for cmd, desc in {**COMMANDS, **custom_commands(self.agent)}.items():
                 if cmd.startswith(text):
                     yield Completion(cmd, start_position=-len(text), display_meta=desc)
             return
@@ -382,6 +382,48 @@ def agents_command(agent: Agent, arg: str) -> None:
     )
 
 
+def custom_commands(agent: Agent) -> dict[str, str]:
+    """The user's and the repository's commands and skills, as /name -> description (built-ins win)."""
+    ext = agent.extensions()
+    found = {f"/{name}": skill.description for name, skill in ext.skills.items()}
+    found.update({f"/{name}": command.description for name, command in ext.commands.items()})
+    return {name: description for name, description in found.items() if name not in COMMANDS}
+
+
+def help_extensions(agent: Agent) -> None:
+    c, ext = agent.console, agent.extensions()
+    if ext.commands:
+        table = Table(title="Your commands", title_justify="left", header_style="bold")
+        for column in ("Command", "Does", "From"):
+            table.add_column(column)
+        for command in ext.commands.values():
+            hidden = " [yellow](hidden by the built-in command)[/]" if f"/{command.name}" in COMMANDS else ""
+            usage = f"/{command.name}" + (f" {command.argument_hint}" if command.argument_hint else "")
+            table.add_row(escape(usage), escape(command.description) + hidden, escape(agent.tools.rel(command.path)))
+        c.print(table)
+    if ext.skills:
+        table = Table(
+            title="Skills (the model loads them when a task matches; /name runs one)",
+            title_justify="left",
+            header_style="bold",
+        )
+        for column in ("Skill", "Does", "From"):
+            table.add_column(column)
+        for skill in ext.skills.values():
+            description = skill.description if len(skill.description) <= 140 else skill.description[:139] + "…"
+            if f"/{skill.name}" in COMMANDS or skill.name in ext.commands:
+                description += f" [yellow](/{skill.name} runs the command; the model can still load the skill)[/]"
+            table.add_row(f"/{escape(skill.name)}", escape(description), escape(agent.tools.rel(skill.folder)))
+        c.print(table)
+    for problem in ext.problems:
+        c.print(f"[yellow]Skipped {escape(problem)}[/]")
+    if not agent.settings.trust_project and extensions.status(agent.cwd) in ("new", "changed"):
+        c.print(
+            "[dim]This repository's own commands, skills and agents aren't in use: you didn't approve them "
+            "(restart lcode here to be asked again).[/]"
+        )
+
+
 def memory_status(agent: Agent) -> str:
     project, user = agent.memory().counts()
     if not (project or user):
@@ -716,6 +758,7 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
             "@path = attach a file · Shift+Tab = cycle permission mode"
         )
         c.print(Panel(f"{rows}\n\n  [dim]{keys}[/]", title="lcode commands", border_style="cyan"))
+        help_extensions(agent)
     elif cmd == "/clear":
         memory_notes.reflect(agent)
         agent.new_session()
@@ -807,6 +850,23 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
         agent.tools.show_todos()
     elif cmd == "/init":
         run_safely(agent, INIT_PROMPT)
+    elif cmd[1:] in agent.extensions().commands:
+        command = agent.extensions().commands[cmd[1:]]
+        c.print(f"[dim]/{escape(command.name)} from {escape(agent.tools.rel(command.path))}[/]")
+        c.print(Rule(style="dim"))
+        previous = agent.allowed_tools
+        if command.tools is not None:
+            agent.allowed_tools = set(command.tools)
+        try:
+            run_safely(agent, command.render(arg))
+        finally:
+            agent.allowed_tools = previous
+    elif cmd[1:] in agent.extensions().skills:
+        skill = agent.extensions().skills[cmd[1:]]
+        agent.skills_loaded.add(skill.name)
+        c.print(f"[dim]Using the {escape(skill.name)} skill from {escape(agent.tools.rel(skill.folder))}[/]")
+        c.print(Rule(style="dim"))
+        run_safely(agent, f"{arg or f'Use the {skill.name} skill.'}\n\n{extensions.content(skill)}")
     else:
         c.print(f"[red]Unknown command {cmd}.[/] Type /help.")
     return True

lcode/subagents.py

@@ -45,7 +45,7 @@ from rich.text import Text
 
 from lcode import config
 from lcode.checkpoints import _clean_env, work_tree_for
-from lcode.memory import frontmatter
+from lcode.frontmatter import split as frontmatter
 from lcode.ollama import OllamaError
 
 if TYPE_CHECKING:
@@ -53,7 +53,7 @@ if TYPE_CHECKING:
     from lcode.permissions import Permissions
 
 READ_ONLY_TOOLS = frozenset(
-    {"read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write"}
+    {"read_file", "list_dir", "glob", "grep", "bash", "web_search", "web_fetch", "view_image", "todo_write", "skill"}
 )
 EDIT_TOOLS = frozenset({"write_file", "edit_file"})
 NOT_FOR_SUBAGENTS = frozenset({"agent", "memory"})  # no agents inside agents; only the main session remembers
@@ -123,9 +123,9 @@ BUILT_IN = {
 # ----------------------------------------------------------------------------- agent types
 
 
-def agent_dirs(cwd: Path) -> list[Path]:
-    """Where custom agents live, lowest priority first: the user's, then the repository's."""
-    return [config.CONFIG_DIR / "agents", work_tree_for(cwd) / ".lcode" / "agents"]
+def agent_dirs(cwd: Path, include_project: bool = True) -> list[Path]:
+    """Where custom agents live, lowest priority first: the user's, then the repository's (once approved)."""
+    return [config.CONFIG_DIR / "agents", *([work_tree_for(cwd) / ".lcode" / "agents"] if include_project else [])]
 
 
 def parse_agent(text: str, name: str, source: str) -> AgentType:
@@ -173,11 +173,11 @@ def parse_agent(text: str, name: str, source: str) -> AgentType:
     )
 
 
-def load_types(cwd: Path) -> tuple[dict[str, AgentType], list[str]]:
+def load_types(cwd: Path, include_project: bool = True) -> tuple[dict[str, AgentType], list[str]]:
     """The agent types for `cwd` (custom ones override built-in ones), and problems with custom ones."""
     types = dict(BUILT_IN)
     problems = []
-    for folder in agent_dirs(cwd):
+    for folder in agent_dirs(cwd, include_project):
         if not folder.is_dir():
             continue
         for f in sorted(folder.glob("*.md")):

lcode/tools.py

@@ -215,7 +215,7 @@ PRESENT_PLAN_SCHEMA = _fn(
 TOOL_NAMES = {
     s["function"]["name"]
     for s in [*SCHEMAS, WEB_SEARCH_SCHEMA, WEB_FETCH_SCHEMA, VIEW_IMAGE_SCHEMA, MEMORY_SCHEMA, PRESENT_PLAN_SCHEMA]
-}
+} | {"agent", "skill"}  # those two have schemas that depend on the session
 
 
 # ----------------------------------------------------------------------------- helpers
@@ -334,10 +334,15 @@ class Toolbox:
         p = Path(os.path.expanduser(path or "."))
         return (p if p.is_absolute() else self.agent.cwd / p).resolve()
 
-    def path(self, path: str | None) -> Path:
-        """Resolve a path from the model; with the sandbox on, it must be inside the project."""
+    def path(self, path: str | None, read: bool = False) -> Path:
+        """Resolve a path from the model; with the sandbox on, it must be inside the project (or, for
+        reading, inside a skill's folder)."""
         p = self.resolve(path)
         root = self.agent.sandbox_root()
+        if read and root is not None:
+            skills = self.agent.extensions().skills.values()
+            if any(p == s.folder or s.folder in p.parents for s in skills):
+                return p
         if root is not None and p != root and root not in p.parents:
             raise ToolError(f"{path} is outside the project ({root}); with the sandbox on, that's all you can use")
         return p
@@ -406,6 +411,15 @@ class Toolbox:
 
         return present(self.agent, title, plan)
 
+    # -- skills
+    def t_skill(self, name: str) -> str:
+        from lcode.extensions import activate
+
+        result = activate(self.agent, name)
+        if not result.startswith("Error:"):
+            self.console.print(Text(f"  ⎿ loaded the {name} skill", style="dim"))
+        return result
+
     # -- memory
     def t_memory(
         self, action: str, name: str = "", type: str = "", description: str = "", details: str = "", scope: str = ""
@@ -459,7 +473,7 @@ class Toolbox:
 
     # -- read-only
     def t_read_file(self, path: str, offset: int = 1, limit: int = 2000) -> str:
-        p = self.path(path)
+        p = self.path(path, read=True)
         if not p.exists():
             raise ToolError(f"{path} does not exist")
         if p.is_dir():
@@ -481,7 +495,7 @@ class Toolbox:
         return truncate(out, 120_000)
 
     def t_list_dir(self, path: str = ".", depth: int = 2) -> str:
-        p = self.path(path)
+        p = self.path(path, read=True)
         if not p.is_dir():
             raise ToolError(f"{path} is not a directory")
         return tree(p, depth=max(1, min(int(depth or 2), 6)))

{lcode_cli-0.9.0.dist-info → lcode_cli-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.9.0
+Version: 0.10.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -80,6 +80,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   your approval. `auto-edit` and `yolo` modes when you want speed.
 - **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
   Podman) that only sees your project, without network access unless you allow it.
+- **Commands and skills.** Your own `/commands` as prompt templates, and skills in the
+  [Agent Skills](https://agentskills.io) format that the model loads only when a task needs them.
 - **Plan mode.** `/plan <request>` or Shift+Tab: the model explores read-only and presents a plan;
   you approve, edit or send it back before anything changes.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
@@ -197,7 +199,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [Custom commands and skills](https://github.com/nasser1941/lcode/issues/42)
 - [Ready-made MCP for Metabase, Encord and Valohai](https://github.com/nasser1941/lcode/issues/53)
 - Then: [smarter context for small windows](https://github.com/nasser1941/lcode/issues/46), [language servers](https://github.com/nasser1941/lcode/issues/44), [a repository map with local embeddings](https://github.com/nasser1941/lcode/issues/45), [hooks](https://github.com/nasser1941/lcode/issues/43)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))

{lcode_cli-0.9.0.dist-info → lcode_cli-0.10.0.dist-info}/RECORD

@@ -1,24 +1,26 @@
-lcode/__init__.py,sha256=nFv9AKdtRRoIhmSP_gIiY5ftUlCFh_s-FQeBjbqj6fI,117
+lcode/__init__.py,sha256=Vt4u1brdsy5UMBysZVsHXtLIwN6S7GISlXj5GAGQI1w,118
 lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
-lcode/agent.py,sha256=fP52AvWe7WfTXmzbM9BH-_rIUtdEf2Ix1iBspeqcTr4,39130
+lcode/agent.py,sha256=5vSYZYFg-5doSF1yx3YRWI8hKSMCxPnSNzJiIwicY_8,40626
 lcode/bench.py,sha256=FCn94Gs7L8bpq4hzf6ILoQG8dKrbbd5WC4BRwrTp4LM,37950
 lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
 lcode/checkpoints.py,sha256=eqPtmPe44-aweWqc2H21ROogwzIt3NpvcUobsaCHoGY,18354
-lcode/cli.py,sha256=Bh9wdAe5fZPzfKUdsbebpMObxqKxLZIDsI3OldhddO8,29610
-lcode/config.py,sha256=Wle_Gwv-FWQmD9jBt8jiHNtmdn3O5bOgkrZ6tbD7_9o,7947
+lcode/cli.py,sha256=2xSELCKgYyqvJUAwG6P6qimZq6wmZGxwYAxCYfeZ7rk,30509
+lcode/config.py,sha256=HwOAz-9LFkH9hOlQwPPG26oIGtOfd0b2Wq2I09WxIAE,8297
+lcode/extensions.py,sha256=1MkCmfvQvcJt1XaqIEOYUruCTsrfQVI5TXOTWBkkJtI,15882
+lcode/frontmatter.py,sha256=Bx0n4vLPhp7ZCWx-g7xqzqNy5VoKBxyeeikh5UFB_gA,2441
 lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
 lcode/limits.py,sha256=oJzVQoMyTZ0_Fkpu5t3qxrf9v7Hv9S8U8BRQR5M1aKA,1237
-lcode/memory.py,sha256=SWB_xt_fdL2hX1mcUqK0drU7laZmg1CqIs0IIAehnCo,22361
+lcode/memory.py,sha256=WZEHTp-lVxAwS-yyLQR2xB3TMZ9sejmX2Ivg7T-tl3w,21949
 lcode/models.toml,sha256=lt2G64zzo_Ryxv2ISRSNZoVD_JqCqYqsM01n8WoXGs8,4098
 lcode/ollama.py,sha256=0f2rkrm3_5Xcnuyvaxcfx5SeYVyRvHjiROXryHKmRUw,7085
 lcode/permissions.py,sha256=m8YNtCladVAmXB20ca8AwyfEOzHKS557B0SOvx1oHeM,4528
-lcode/planning.py,sha256=C7_JyArIywPygU9DdfaoN2EfgA6JGNnKafuIilkOzGw,6067
+lcode/planning.py,sha256=Z30K2tbqoy2XimKwth1lYYz7OVaQUXGdDvBgops7pGE,6076
 lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
-lcode/repl.py,sha256=K04EpyIxyrP6I3oPh9tp8xqoIubplqHRXvWbqFdOKks,40356
+lcode/repl.py,sha256=FnyYpRuvpqmIVWQbMSvagrFBvFcLjIAedFeF32u5Vp4,43612
 lcode/sandbox.py,sha256=u_pkrVRXhCGhh-wFDPwuZ3jGG7UeXxXRAeBNsm37ZvE,8608
 lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
-lcode/subagents.py,sha256=L5U-USz2fnGOx3Z28_sOA6btWmMKSGXVbFKQYcrZSDM,28147
-lcode/tools.py,sha256=VNhNkC43x2l20kqv06cbDXmdJHugDncFX0AIUfAr3CE,34820
+lcode/subagents.py,sha256=ILGFwdFWfwKqExl2D5h_AArqlOris2N0aqh3Ccj895Q,28295
+lcode/tools.py,sha256=Af2pbx8KIR4uLaWk2opbzMY8ZFQ22mGcu8FnRbX9DsM,35486
 lcode/vision.py,sha256=w33QPmdGwP33wM4mvmAH4amFDZ1xzeXhEsSLJ-STSHY,4243
 lcode/web.py,sha256=vyxKbSRJTl1Lj3hj7Yd_NwTgbv0Xi6dup2YfUXjqp-Y,14579
 lcode/mcp/__init__.py,sha256=XujtAmRoXW9S0uq1XPf_CAeCkHh_UvA8FCmoAKP9j1Y,171
@@ -32,8 +34,8 @@ lcode/mcp/http.py,sha256=sG9MajwU4_6sqvZhwD4WfyzRKzaR_Lc8C02jwePz18E,7380
 lcode/mcp/manager.py,sha256=79nNWoT5pxgoQD_Pv4ZH0obHIm7rQ-LyB8OmJnQgc6k,15104
 lcode/mcp/protocol.py,sha256=-xwhA2Tz-vzR2zdSdbPx4IjTu29uRrXMaePg0vEz_Vc,5223
 lcode/mcp/stdio.py,sha256=kC6KHwzMMDjBr-yCZLmyVKS7PZXU299WpZdYRoX5eRQ,6292
-lcode_cli-0.9.0.dist-info/METADATA,sha256=DW7hETwyh_0QCwMacZY-ofQbFPMPZTgChvrxjXDTb-8,11379
-lcode_cli-0.9.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-lcode_cli-0.9.0.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
-lcode_cli-0.9.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
-lcode_cli-0.9.0.dist-info/RECORD,,
+lcode_cli-0.10.0.dist-info/METADATA,sha256=qlFYNWlZjDePi7kqZ2JnRUVasJODV0Emqu6SDFhKvhI,11487
+lcode_cli-0.10.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lcode_cli-0.10.0.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
+lcode_cli-0.10.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
+lcode_cli-0.10.0.dist-info/RECORD,,