Recipe: Agent Skills Support

This recipe is about using the existing lectic skills plugin and creating skills for it. It does not walk through implementing the subcommand itself.

What are Agent Skills?

Agent Skills is an open format for packaging reusable capabilities that LLMs can load on demand. A skill is a folder containing:

  • SKILL.md: instructions for the LLM (with YAML frontmatter)
  • scripts/: executable scripts the LLM can run
  • references/: docs and examples the LLM can read

The format emphasizes progressive disclosure:

  1. Discovery: see only skill names and descriptions.
  2. Activation: load full instructions for one skill.
  3. Resources: read files or run scripts only when needed.

Prerequisite

This recipe assumes lectic skills is already available in your runtime (via your plugin setup).

Create a skill

A skill root must contain SKILL.md with at least name and description in frontmatter.

Example layout:

skills/
  pdf-processing/
    SKILL.md
    scripts/
      extract.py
    references/
      REFERENCE.md

Example SKILL.md:

---
name: pdf-processing
description: Extract and summarize text from PDFs.
---

Use this skill when the user asks about PDF content.

1. Run `scripts/extract.py` to extract text.
2. Read `references/REFERENCE.md` for edge cases and options.

Notes:

  • name must match the directory name.
  • Keep descriptions short and specific.
  • Put heavy details in references, not in the description.

Point Lectic at your skills

Configure a tool that calls the subcommand.

Use default discovery (runtime/data):

tools:
  - name: skills
    exec: lectic skills
    usage: exec:lectic skills --prompt

Pass explicit roots by placing them before --:

tools:
  - name: skills
    exec: lectic skills ./skills $LECTIC_DATA/skills --
    usage: exec:lectic skills ./skills $LECTIC_DATA/skills -- --prompt

--prompt includes the discovery list in tool usage text, so the model usually does not need to call list.

How discovery works

lectic skills has two modes:

  1. Default roots mode (no --):
    • uses LECTIC_RUNTIME and LECTIC_DATA recursively.
  2. Explicit roots mode (ROOT ... -- ...):
    • all args before -- are root selectors.
    • all args after -- are command args.

Each explicit root selector may be either:

  • a runtime skill name (for example serve),
  • an explicit filesystem path to a skill root (./foo or /foo), or
  • an explicit path to a directory whose immediate children are skill roots.

Important:

  • Filesystem roots must start with . or /.
  • Bare selectors that do not match runtime skill names are errors.
  • lectic skills -- ... means explicit-roots mode with zero roots, which is equivalent to default roots mode.

Model workflow

Typical tool calls:

  1. Activate a skill:
<tool-call with="skills">
<arguments><argv>["activate","pdf-processing"]</argv></arguments>
...</tool-call>
  1. Read a referenced file:
<tool-call with="skills">
<arguments><argv>["read","pdf-processing","references/REFERENCE.md"]</argv></arguments>
...</tool-call>
  1. Run a skill script:
<tool-call with="skills">
<arguments><argv>["run","pdf-processing","extract.py","--input","a.pdf"]
</argv></arguments>
...</tool-call>

Safety notes

Running skill scripts is effectively another exec capability. In practice, combine this with one or more of:

  • a tool_use_pre confirmation hook
  • a sandbox wrapper (Bubblewrap, nsjail, etc.)

See Custom Sandboxing for concrete options.