Skip to content

Skill System

The Skill System extends Lango's capabilities through file-based skill definitions. Skills are Markdown files (SKILL.md) that define reusable behaviors, scripts, templates, and multi-step workflows -- without writing Go code.

Two independent skill systems

Lango has two skill subsystems that share the term "skill" but serve different layers:

  • This page — the knowledge skill registry (skill.* config, ~/.lango/skills). Uses Lango's own type-tagged frontmatter (instruction / composite / script / template). Skills are loaded by the runtime and contribute to the knowledge layer.
  • ADK SkillToolset — config: agent.skillsDir. Uses agentskills.io frontmatter (name, description). The ADK agent gains three tools at runtime — load_skill, list_skill_resources, load_skill_resource — which it can call to discover and read Markdown-defined skill bundles. See assets/skills/example-skill/ for a reference bundle.

The two systems are independent. Migration of existing ~/.lango/skills Lango-format skills to agentskills.io format is deferred to a future change. For now, you can use both simultaneously (different directories, different purposes).

Skill Types

Type Description Definition
instruction Reference documents that guide agent reasoning Markdown content in the body
composite Multi-step tool chains executed sequentially JSON step definitions
script Shell scripts executed in a sandboxed environment sh/bash code block
template Go templates rendered with parameters template code block

SKILL.md Format

Every skill is defined in a SKILL.md file with YAML frontmatter and a Markdown body:

---
name: my-skill
description: What this skill does
type: instruction
status: active
created_by: user
requires_approval: false
allowed-tools: exec file_read
---

The skill content goes here. For instruction skills,
this entire body is the reference document.

Frontmatter Fields

Field Required Default Description
name Yes -- Unique skill identifier
description No -- Description shown to the agent
type No instruction Skill type: instruction, composite, script, template
status No active Lifecycle status: draft, active, disabled
created_by No -- Creator attribution
requires_approval No false Whether execution requires user approval
allowed-tools No -- Space-separated list of pre-approved tools

Instruction Skills

The Markdown body is stored as the skill content. When invoked, the agent receives this as a reference document:

---
name: coding-guidelines
description: Project coding standards and conventions
type: instruction
---

## Variable Naming
- Use camelCase for local variables
- Use PascalCase for exported functions
...

Script Skills

Shell scripts are defined in an sh or bash code block:

---
name: system-info
description: Gather system information
type: script
---

```sh
echo "OS: $(uname -s)"
echo "CPU: $(nproc) cores"
echo "Memory: $(free -h | awk '/Mem:/{print $2}')"

!!! warning "Script Safety"

    Scripts are validated against dangerous patterns before execution. The following patterns are blocked:

    | Pattern | Threat |
    |---|---|
    | `rm -rf /` | Filesystem destruction |
    | Fork bomb (`:(){ ...\|...& };:`) | Resource exhaustion |
    | `curl\|sh` or `wget\|sh` | Remote code execution |
    | `> /dev/sd*` | Disk overwrite |
    | `mkfs.*` | Filesystem formatting |
    | `dd if=` | Raw disk write |

    Pattern blocking provides a basic safety net but is not a comprehensive sandbox. Review imported skills before enabling them, especially scripts from untrusted sources.

### Composite Skills

Multi-step tool chains are defined as JSON blocks:

```markdown
---
name: deploy
description: Deploy the application
type: composite
requires_approval: true
---

### Step 1

```json
{
  "tool": "exec",
  "params": {"command": "make build"}
}

Step 2

{
  "tool": "exec",
  "params": {"command": "make deploy"}
}

### Template Skills

Go templates with parameter substitution:

```markdown
---
name: greeting
description: Generate a greeting message
type: template
---

```template
Hello, {{.name}}! Welcome to {{.project}}.

Parameters

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "User's name"},
    "project": {"type": "string", "description": "Project name"}
  }
}

## Skill Lifecycle

Skills progress through three statuses:
draft → active → disabled 
- **Draft** -- Created but not loaded into the agent
- **Active** -- Loaded and available as an agent tool (prefixed `skill_`)
- **Disabled** -- Retained in storage but not loaded

## Importing Skills

Skills can be imported from external sources when `skill.allowImport` is enabled.

### From URLs

Import a single skill from a raw URL:
Use the skill_import tool to import from https://example.com/skills/my-skill/SKILL.md 
### From GitHub Repositories

Import skills from GitHub repositories. Each subdirectory containing a `SKILL.md` file is treated as a skill:
Import skills from https://github.com/owner/repo 
The importer supports:

- **Git clone** (preferred) -- Shallow clone with resource file support (`scripts/`, `references/`, `assets/`)
- **GitHub API fallback** -- When `git` is not available, uses the GitHub Contents API

### Bulk Import

Import all skills from a repository directory at once:
Import all skills from https://github.com/owner/repo/tree/main/skills 
Bulk import respects the `maxBulkImport` limit (default: 50) and runs with configurable concurrency (default: 5).

## Embedded Scaffold

Lango no longer ships a bundle of built-in default skills. The current runtime embeds only a placeholder `SKILL.md` entry so the binary can keep the skill embed path wired without deploying a usable built-in skill by default.

That means the skills directory starts empty until you:

- create your own skills,
- import skills from GitHub or another URL, or
- install extension packs that include skills.

When real embedded skills are added in the future, the deploy path still preserves local customizations: existing skill directories are not overwritten.

## Storage

Skills are stored as Markdown files in the skills directory (default: `~/.lango/skills/`). Each skill gets its own subdirectory:
~/.lango/skills/ my-skill/ SKILL.md scripts/ references/ assets/ 
Resource directories (`scripts/`, `references/`, `assets/`) are automatically imported alongside the skill definition.
Agent-facing skill resource reads are confined to the selected skill directory; lexical escapes and symlinks that resolve outside that directory are rejected.

## Configuration

> **Settings:** `lango settings` → Skill

```json
{
  "skill": {
    "enabled": true,
    "skillsDir": "~/.lango/skills",
    "allowImport": true,
    "maxBulkImport": 50,
    "importConcurrency": 5,
    "importTimeout": "2m"
  }
}

Key Type Default Description
enabled bool false Enable the skill system
skillsDir string ~/.lango/skills Directory containing skill files
allowImport bool false Enable importing skills from URLs and GitHub
maxBulkImport int 50 Maximum skills in a single bulk import
importConcurrency int 5 Concurrent HTTP requests during import
importTimeout duration 2m Overall timeout for import operations

Agent Integration

Active skills are registered as agent tools with the skill_ prefix. For example, a skill named deploy becomes the tool skill_deploy.

The agent uses the skill description to decide when to invoke it. For instruction skills, the agent receives the full reference document when the tool is called.

Skills also feed into the Knowledge System as Layer 3 (Skill Patterns), making them available during context retrieval.