Skip to content
weego edited this page May 28, 2026 · 1 revision

Skills

Skills let LightAgent discover reusable task instructions from directories that contain SKILL.md files. A Skill is useful when a task needs detailed procedures, domain-specific rules, reference files, scripts, or assets.

Skill Directory

Default discovery looks under skills/:

skills/
  market-research/
    SKILL.md
    references/
    scripts/
    assets/

You can pass custom directories:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    skills_directories=["skills", "company_skills"],
)

SKILL.md Format

SKILL.md must start with YAML frontmatter:

---
name: market-research
description: Use this skill for market research, competitor scans, and source-backed summaries.
---

# Instructions

Follow this workflow when the user asks for market research...

Required frontmatter fields:

  • name
  • description

How Activation Works

On startup, LightAgent discovers Skill metadata only. When Skills exist, the agent receives metadata and Skill tools:

  • list_skills
  • activate_skill
  • execute_skill_script
  • read_skill_reference

The model can call activate_skill to load the full SKILL.md instructions into context when a user request matches a Skill description.

Scripts, References, and Assets

Optional directories:

  • scripts/: executable helper scripts for deterministic work.
  • references/: documents the Skill can read on demand.
  • assets/: binary resources the Skill can use.

Keep scripts narrow and auditable. A Skill should not need broad filesystem or network side effects unless the use case requires them.

Disable Auto Discovery

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    auto_discover_skills=False,
)

Best Practices

  • Keep descriptions specific so activation is predictable.
  • Put long procedures in the body of SKILL.md, not in the description.
  • Put large references in references/ and load them only when needed.
  • Prefer scripts for deterministic file conversion, parsing, or validation.
  • Review third-party Skills before running their scripts.

Clone this wiki locally