agentlings 0.2.3__tar.gz → 0.4.0__tar.gz

{agentlings-0.2.3 → agentlings-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlings
-Version: 0.2.3
+Version: 0.4.0
 Summary: Lightweight A2A + MCP single-process agent framework
 Project-URL: Homepage, https://github.com/andyjmorgan/DonkeyWork-Agentlings
 Project-URL: Repository, https://github.com/andyjmorgan/DonkeyWork-Agentlings
@@ -37,7 +37,7 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="logo.png" alt="Agentlings" width="256">
+  <img src="media/logo.png" alt="Agentlings" width="256">
 </p>
 
 <h1 align="center">Agentlings</h1>
@@ -82,8 +82,10 @@ my-agent/
 ├── .env                 # AGENT_API_KEY auto-generated; ANTHROPIC_API_KEY blank for you
 ├── .env.example         # checked into source control as a template
 ├── .framework-version   # the framework version that scaffolded this dir
-└── data/                # journals, memory, conversations
-    └── .migrations      # applied-migrations log
+├── data/                # journals, memory, conversations
+│   └── .migrations      # applied-migrations log
+├── skills/              # drop SKILL.md bundles here; uncomment AGENT_SKILLS_DIR to enable
+└── tools/               # drop @tool-decorated .py files here; uncomment AGENT_TOOLS_DIR to enable
 ```
 
 `agentling run` reads `agent.yaml`, `.env`, and `data/` from the current directory. To operate on a different dir without `cd`-ing in: `agentling run --dir /path/to/agent`.
@@ -95,6 +97,8 @@ The running agent serves:
 - `POST /a2a` — A2A JSON-RPC endpoint
 - `POST /mcp` — MCP Streamable HTTP endpoint
 
+Both protocols are task-aware. Each request becomes a task; the HTTP handler awaits up to `AGENT_TASK_AWAIT_SECONDS` (default 60) and either returns the final answer inline or yields a task handle the caller polls. A2A clients can opt out of the wait per-request via `configuration.return_immediately = true` on `message/send` (A2A v1.0 JSON name `returnImmediately`) — the handler then enqueues a `Task` object immediately and the caller polls via `tasks/get`.
+
 ## CLI
 
 | Command | Purpose |
@@ -222,7 +226,106 @@ Point to it with `AGENT_CONFIG=./agent.yaml`.
 | `filesystem` | `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files` | File operations with offset/limit, find-and-replace, glob search |
 | `memory` | `memory_edit` | Read and write the agent's persistent long-term memory |
 
-Tools are off by default. Run `agentling --list-tools` for details.
+Tools are off by default. Run `agentling list-tools` for details.
+
+## Custom tools
+
+<p align="center">
+  <img src="media/tools.png" alt="Custom tools" width="256">
+</p>
+
+Beyond the built-ins, you can author your own tools as plain typed Python functions. Decorate them with `@tool`, drop the file in a directory, and point `AGENT_TOOLS_DIR` at it — the agentling scans the directory at startup and registers every `Tool` it finds.
+
+```python
+# tools/weather.py
+import os
+from typing import Annotated, Literal
+from pydantic import Field
+from agentlings.tools import tool
+
+
+@tool
+async def weather(
+    city: Annotated[str, Field(description="City name, e.g. 'Dublin'.")],
+    units: Literal["metric", "imperial"] = "metric",
+) -> str:
+    """Look up current weather for a city."""
+    api_key = os.environ["WEATHER_API_KEY"]
+    # ...fetch and return a string the LLM can read...
+```
+
+Then run with `AGENT_TOOLS_DIR=./tools agentling run`. No registration step, no schema dict — the JSON Schema the LLM sees is derived from the function signature via Pydantic.
+
+### How discovery works
+
+- The loader scans the top level of `AGENT_TOOLS_DIR` for `.py` files (no recursion).
+- Files whose name begins with `_` are skipped (use them for shared helpers).
+- Each file is imported in isolation — the directory is never added to `sys.path`, so a file named `json.py` cannot shadow the stdlib.
+- Every module-level `Tool` instance (i.e. anything you decorated with `@tool`) is registered.
+- An import or registration failure on one file is logged and the scan continues — one broken tool cannot brick the agent.
+
+### Authoring contract
+
+| Concept | How to express it |
+|---|---|
+| Tool name | `func.__name__` (or `@tool(name="...")`) |
+| Tool description | The function's docstring (or `@tool(description="...")`) |
+| Parameter description / constraints | `Annotated[T, Field(description="...", ge=..., le=...)]` |
+| Allowed values | `Literal["a", "b"]` or a `str`/`int` `Enum` |
+| Optional / defaults | A normal Python default (`x: int = 30`) |
+| Async I/O | `async def` — sync functions are fine too; both are awaited uniformly |
+| Per-tool secrets | Read your own env vars inside the function (the framework stays out of secret plumbing) |
+
+Untyped parameters, `*args`, `**kwargs`, and positional-only parameters are rejected at decoration time — `@tool` raises `ToolDefinitionError` so misuse fails loudly at startup, not in production.
+
+Reference tools showcasing each pattern live in `agentlings.tools.examples` (`echo`, `http_get`, `set_severity`, `geocode`).
+
+## Skills
+
+<p align="center">
+  <img src="media/skills.png" alt="Skills" width="256">
+</p>
+
+Skills are bundled instructions the agent activates on demand. Each skill is a directory containing a `SKILL.md` whose YAML frontmatter (`name`, `description`) is loaded into the system prompt at startup; the body — and any sibling `scripts/`, `references/`, or `assets/` — stays on disk until the agent decides the task needs it. This is the **progressive disclosure** model from the [Open Skills specification](https://agentskills.io/specification): metadata is cheap, instructions are loaded on activation, resources are loaded on demand.
+
+```
+skills/
+├── pdf-processing/
+│   ├── SKILL.md
+│   ├── scripts/extract.py
+│   └── references/FORMS.md
+└── data-analysis/
+    └── SKILL.md
+```
+
+A minimal `SKILL.md`:
+
+```markdown
+---
+name: pdf-processing
+description: Extract text and tables from PDFs, fill PDF forms, merge files. Use when the user mentions PDFs, forms, or document extraction.
+---
+
+Step-by-step instructions for the agent go below the frontmatter.
+Reference companion files with relative paths, e.g. `scripts/extract.py`.
+```
+
+Skills are opt-in: set `AGENT_SKILLS_DIR=./skills` (or any path) and drop skill directories there. On startup the agentling discovers them and prepends a single block to the system prompt explaining progressive disclosure and listing each skill's name, absolute path, and description. The agent reads `SKILL.md` itself when a task calls for the skill.
+
+### Frontmatter constraints
+
+Per the Open Skills spec:
+
+| Field | Required | Constraint |
+|---|---|---|
+| `name` | Yes | 1–64 chars, lowercase `a-z`, digits, hyphens; no leading/trailing/consecutive hyphens; must match the parent directory name |
+| `description` | Yes | 1–1024 chars, non-empty |
+
+Optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) are accepted but currently ignored at the runtime layer. Malformed skills (missing fields, invalid names, broken YAML) are logged at `WARNING` and skipped — one bad skill does not prevent the agent from booting.
+
+Discovery is strictly read-only — the agentling never writes to, deletes from, or modifies anything under `AGENT_SKILLS_DIR`. `AGENT_SKILLS_DIR` and `AGENT_TOOLS_DIR` share the same opt-in semantics: unset means "don't scan." `AGENT_TOOLS_DIR` additionally never adds the user-tools directory to `sys.path`, so a file named `json.py` cannot shadow the stdlib.
+
+> **Naming note:** the `skills:` array in `agent.yaml` is unrelated — those are A2A Agent Card capabilities advertised on the wire. Runtime skills (this section) live on disk under `AGENT_SKILLS_DIR`.
 
 ## Docker
 
@@ -260,6 +363,9 @@ Secrets and runtime settings stay in env vars or, more commonly, the `.env` file
 | `AGENT_HOST` | `0.0.0.0` | Bind address |
 | `AGENT_PORT` | `8420` | Bind port |
 | `AGENT_DATA_DIR` | `./data` | JSONL journal storage directory |
+| `AGENT_TOOLS_DIR` | — | Directory of `@tool`-decorated `.py` files to load at startup |
+| `AGENT_SKILLS_DIR` | — | Directory of Open Skills `SKILL.md` bundles to advertise to the agent |
+| `AGENT_TASK_AWAIT_SECONDS` | `60` | How long the HTTP handler blocks for task completion before returning a working task handle |
 | `AGENT_LOG_LEVEL` | `INFO` | Log level |
 | `AGENT_LLM_BACKEND` | `anthropic` | `anthropic` or `mock` |
 | `AGENT_EXTERNAL_URL` | — | Public URL for Agent Card (needed in Docker/k8s) |
@@ -320,7 +426,7 @@ memory:
 ## Sleep cycle
 
 <p align="center">
-  <img src="sleep.png" alt="Sleep Cycle" width="256">
+  <img src="media/sleep.png" alt="Sleep Cycle" width="256">
 </p>
 
 The sleep cycle is a nightly process that journals the day's activity, consolidates new knowledge into memory, prunes stale entries, and cleans up old files. It maps to biological sleep phases.

{agentlings-0.2.3 → agentlings-0.4.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="logo.png" alt="Agentlings" width="256">
+  <img src="media/logo.png" alt="Agentlings" width="256">
 </p>
 
 <h1 align="center">Agentlings</h1>
@@ -44,8 +44,10 @@ my-agent/
 ├── .env                 # AGENT_API_KEY auto-generated; ANTHROPIC_API_KEY blank for you
 ├── .env.example         # checked into source control as a template
 ├── .framework-version   # the framework version that scaffolded this dir
-└── data/                # journals, memory, conversations
-    └── .migrations      # applied-migrations log
+├── data/                # journals, memory, conversations
+│   └── .migrations      # applied-migrations log
+├── skills/              # drop SKILL.md bundles here; uncomment AGENT_SKILLS_DIR to enable
+└── tools/               # drop @tool-decorated .py files here; uncomment AGENT_TOOLS_DIR to enable
 ```
 
 `agentling run` reads `agent.yaml`, `.env`, and `data/` from the current directory. To operate on a different dir without `cd`-ing in: `agentling run --dir /path/to/agent`.
@@ -57,6 +59,8 @@ The running agent serves:
 - `POST /a2a` — A2A JSON-RPC endpoint
 - `POST /mcp` — MCP Streamable HTTP endpoint
 
+Both protocols are task-aware. Each request becomes a task; the HTTP handler awaits up to `AGENT_TASK_AWAIT_SECONDS` (default 60) and either returns the final answer inline or yields a task handle the caller polls. A2A clients can opt out of the wait per-request via `configuration.return_immediately = true` on `message/send` (A2A v1.0 JSON name `returnImmediately`) — the handler then enqueues a `Task` object immediately and the caller polls via `tasks/get`.
+
 ## CLI
 
 | Command | Purpose |
@@ -184,7 +188,106 @@ Point to it with `AGENT_CONFIG=./agent.yaml`.
 | `filesystem` | `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files` | File operations with offset/limit, find-and-replace, glob search |
 | `memory` | `memory_edit` | Read and write the agent's persistent long-term memory |
 
-Tools are off by default. Run `agentling --list-tools` for details.
+Tools are off by default. Run `agentling list-tools` for details.
+
+## Custom tools
+
+<p align="center">
+  <img src="media/tools.png" alt="Custom tools" width="256">
+</p>
+
+Beyond the built-ins, you can author your own tools as plain typed Python functions. Decorate them with `@tool`, drop the file in a directory, and point `AGENT_TOOLS_DIR` at it — the agentling scans the directory at startup and registers every `Tool` it finds.
+
+```python
+# tools/weather.py
+import os
+from typing import Annotated, Literal
+from pydantic import Field
+from agentlings.tools import tool
+
+
+@tool
+async def weather(
+    city: Annotated[str, Field(description="City name, e.g. 'Dublin'.")],
+    units: Literal["metric", "imperial"] = "metric",
+) -> str:
+    """Look up current weather for a city."""
+    api_key = os.environ["WEATHER_API_KEY"]
+    # ...fetch and return a string the LLM can read...
+```
+
+Then run with `AGENT_TOOLS_DIR=./tools agentling run`. No registration step, no schema dict — the JSON Schema the LLM sees is derived from the function signature via Pydantic.
+
+### How discovery works
+
+- The loader scans the top level of `AGENT_TOOLS_DIR` for `.py` files (no recursion).
+- Files whose name begins with `_` are skipped (use them for shared helpers).
+- Each file is imported in isolation — the directory is never added to `sys.path`, so a file named `json.py` cannot shadow the stdlib.
+- Every module-level `Tool` instance (i.e. anything you decorated with `@tool`) is registered.
+- An import or registration failure on one file is logged and the scan continues — one broken tool cannot brick the agent.
+
+### Authoring contract
+
+| Concept | How to express it |
+|---|---|
+| Tool name | `func.__name__` (or `@tool(name="...")`) |
+| Tool description | The function's docstring (or `@tool(description="...")`) |
+| Parameter description / constraints | `Annotated[T, Field(description="...", ge=..., le=...)]` |
+| Allowed values | `Literal["a", "b"]` or a `str`/`int` `Enum` |
+| Optional / defaults | A normal Python default (`x: int = 30`) |
+| Async I/O | `async def` — sync functions are fine too; both are awaited uniformly |
+| Per-tool secrets | Read your own env vars inside the function (the framework stays out of secret plumbing) |
+
+Untyped parameters, `*args`, `**kwargs`, and positional-only parameters are rejected at decoration time — `@tool` raises `ToolDefinitionError` so misuse fails loudly at startup, not in production.
+
+Reference tools showcasing each pattern live in `agentlings.tools.examples` (`echo`, `http_get`, `set_severity`, `geocode`).
+
+## Skills
+
+<p align="center">
+  <img src="media/skills.png" alt="Skills" width="256">
+</p>
+
+Skills are bundled instructions the agent activates on demand. Each skill is a directory containing a `SKILL.md` whose YAML frontmatter (`name`, `description`) is loaded into the system prompt at startup; the body — and any sibling `scripts/`, `references/`, or `assets/` — stays on disk until the agent decides the task needs it. This is the **progressive disclosure** model from the [Open Skills specification](https://agentskills.io/specification): metadata is cheap, instructions are loaded on activation, resources are loaded on demand.
+
+```
+skills/
+├── pdf-processing/
+│   ├── SKILL.md
+│   ├── scripts/extract.py
+│   └── references/FORMS.md
+└── data-analysis/
+    └── SKILL.md
+```
+
+A minimal `SKILL.md`:
+
+```markdown
+---
+name: pdf-processing
+description: Extract text and tables from PDFs, fill PDF forms, merge files. Use when the user mentions PDFs, forms, or document extraction.
+---
+
+Step-by-step instructions for the agent go below the frontmatter.
+Reference companion files with relative paths, e.g. `scripts/extract.py`.
+```
+
+Skills are opt-in: set `AGENT_SKILLS_DIR=./skills` (or any path) and drop skill directories there. On startup the agentling discovers them and prepends a single block to the system prompt explaining progressive disclosure and listing each skill's name, absolute path, and description. The agent reads `SKILL.md` itself when a task calls for the skill.
+
+### Frontmatter constraints
+
+Per the Open Skills spec:
+
+| Field | Required | Constraint |
+|---|---|---|
+| `name` | Yes | 1–64 chars, lowercase `a-z`, digits, hyphens; no leading/trailing/consecutive hyphens; must match the parent directory name |
+| `description` | Yes | 1–1024 chars, non-empty |
+
+Optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) are accepted but currently ignored at the runtime layer. Malformed skills (missing fields, invalid names, broken YAML) are logged at `WARNING` and skipped — one bad skill does not prevent the agent from booting.
+
+Discovery is strictly read-only — the agentling never writes to, deletes from, or modifies anything under `AGENT_SKILLS_DIR`. `AGENT_SKILLS_DIR` and `AGENT_TOOLS_DIR` share the same opt-in semantics: unset means "don't scan." `AGENT_TOOLS_DIR` additionally never adds the user-tools directory to `sys.path`, so a file named `json.py` cannot shadow the stdlib.
+
+> **Naming note:** the `skills:` array in `agent.yaml` is unrelated — those are A2A Agent Card capabilities advertised on the wire. Runtime skills (this section) live on disk under `AGENT_SKILLS_DIR`.
 
 ## Docker
 
@@ -222,6 +325,9 @@ Secrets and runtime settings stay in env vars or, more commonly, the `.env` file
 | `AGENT_HOST` | `0.0.0.0` | Bind address |
 | `AGENT_PORT` | `8420` | Bind port |
 | `AGENT_DATA_DIR` | `./data` | JSONL journal storage directory |
+| `AGENT_TOOLS_DIR` | — | Directory of `@tool`-decorated `.py` files to load at startup |
+| `AGENT_SKILLS_DIR` | — | Directory of Open Skills `SKILL.md` bundles to advertise to the agent |
+| `AGENT_TASK_AWAIT_SECONDS` | `60` | How long the HTTP handler blocks for task completion before returning a working task handle |
 | `AGENT_LOG_LEVEL` | `INFO` | Log level |
 | `AGENT_LLM_BACKEND` | `anthropic` | `anthropic` or `mock` |
 | `AGENT_EXTERNAL_URL` | — | Public URL for Agent Card (needed in Docker/k8s) |
@@ -282,7 +388,7 @@ memory:
 ## Sleep cycle
 
 <p align="center">
-  <img src="sleep.png" alt="Sleep Cycle" width="256">
+  <img src="media/sleep.png" alt="Sleep Cycle" width="256">
 </p>
 
 The sleep cycle is a nightly process that journals the day's activity, consolidates new knowledge into memory, prunes stale entries, and cleans up old files. It maps to biological sleep phases.

{agentlings-0.2.3 → agentlings-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentlings"
-version = "0.2.3"
+version = "0.4.0"
 description = "Lightweight A2A + MCP single-process agent framework"
 readme = "README.md"
 license = { text = "MIT" }

{agentlings-0.2.3 → agentlings-0.4.0}/src/agentlings/cli/init.py

@@ -18,6 +18,8 @@ from agentlings.cli import _migrations, _templates, _version
 logger = logging.getLogger(__name__)
 
 DATA_DIRNAME = "data"
+SKILLS_DIRNAME = "skills"
+TOOLS_DIRNAME = "tools"
 ENV_FILENAME = ".env"
 ENV_EXAMPLE_FILENAME = ".env.example"
 YAML_FILENAME = "agent.yaml"
@@ -64,6 +66,8 @@ def init_agent(
 
     target.mkdir(parents=True, exist_ok=True)
     (target / DATA_DIRNAME).mkdir(exist_ok=True)
+    (target / SKILLS_DIRNAME).mkdir(exist_ok=True)
+    (target / TOOLS_DIRNAME).mkdir(exist_ok=True)
 
     yaml_path = target / YAML_FILENAME
     if not yaml_path.exists() or force:

{agentlings-0.2.3 → agentlings-0.4.0}/src/agentlings/config.py

@@ -153,6 +153,7 @@ class AgentConfig(BaseSettings):
     agent_host: str = "0.0.0.0"
     agent_port: int = 8420
     agent_data_dir: Path = Path("./data")
+    agent_skills_dir: Path | None = None
     agent_log_level: str = "INFO"
     agent_llm_backend: Literal["anthropic", "mock"] = "anthropic"
     agent_external_url: str | None = None
@@ -162,6 +163,7 @@ class AgentConfig(BaseSettings):
     agent_otel_insecure: bool = True
     agent_otel_headers: str = ""
     agent_task_await_seconds: int = 60
+    agent_tools_dir: Path | None = None
 
     _definition: AgentDefinition = AgentDefinition()
 
@@ -202,6 +204,16 @@ class AgentConfig(BaseSettings):
         """Skills to advertise from the YAML definition."""
         return self._definition.skills
 
+    @property
+    def skills_dir(self) -> Path | None:
+        """Filesystem root for runtime instruction-skills (Open Skills spec).
+
+        Opt-in: when ``AGENT_SKILLS_DIR`` is unset, the agent does not scan
+        anywhere. This matches ``AGENT_TOOLS_DIR`` so the two folder-scan
+        env vars share one mental model.
+        """
+        return self.agent_skills_dir
+
     @property
     def memory_config(self) -> MemoryConfig | None:
         """Memory configuration from the YAML definition."""

{agentlings-0.2.3 → agentlings-0.4.0}/src/agentlings/core/loop.py

@@ -17,6 +17,7 @@ from typing import Any
 from agentlings.config import AgentConfig
 from agentlings.core.llm import BaseLLMClient
 from agentlings.core.memory_store import MemoryFileStore
+from agentlings.core.skills import SkillRef
 from agentlings.core.store import JournalStore
 from agentlings.core.task import (
     TaskEngine,
@@ -79,6 +80,7 @@ class MessageLoop:
         llm: BaseLLMClient,
         tools: ToolRegistry,
         memory_store: MemoryFileStore | None = None,
+        skills: list[SkillRef] | None = None,
     ) -> None:
         self._config = config
         self._store = store
@@ -88,6 +90,7 @@ class MessageLoop:
             llm=llm,
             tools=tools,
             memory_store=memory_store,
+            skills=skills,
         )
 
     @property

{agentlings-0.2.3 → agentlings-0.4.0}/src/agentlings/core/prompt.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from agentlings.config import AgentConfig
 from agentlings.core.memory_models import MemoryStore
+from agentlings.core.skills import SkillRef, format_skills_block
 
 logger = logging.getLogger(__name__)
 
@@ -40,6 +41,7 @@ def build_system_prompt(
     data_dir: Path | None = None,
     injection_prompt: str | None = None,
     token_budget: int = 2000,
+    skills: list[SkillRef] | None = None,
 ) -> list[dict[str, Any]]:
     """Build the system prompt blocks for the Anthropic Messages API.
 
@@ -49,6 +51,9 @@ def build_system_prompt(
         data_dir: Path to the agent's data directory for the awareness block.
         injection_prompt: Override for the memory injection template.
             Uses ``DEFAULT_MEMORY_INJECTION`` if not provided.
+        skills: Discovered runtime skills (Open Skills spec). Prepended ahead
+            of the identity block when non-empty so the agent sees them
+            before any operator-defined instructions.
 
     Returns:
         A list of text blocks with ``cache_control`` set to ephemeral.
@@ -58,13 +63,21 @@ def build_system_prompt(
     else:
         text = _default_prompt(config)
 
-    blocks = [
-        {
+    blocks: list[dict[str, Any]] = []
+
+    skills_block = format_skills_block(skills or [])
+    if skills_block is not None:
+        blocks.append({
             "type": "text",
-            "text": text,
+            "text": skills_block,
             "cache_control": {"type": "ephemeral"},
-        },
-    ]
+        })
+
+    blocks.append({
+        "type": "text",
+        "text": text,
+        "cache_control": {"type": "ephemeral"},
+    })
 
     if memory and memory.entries:
         template = injection_prompt or DEFAULT_MEMORY_INJECTION

agentlings-0.4.0/src/agentlings/core/skills.py

@@ -0,0 +1,156 @@
+"""Skill discovery and prompt rendering.
+
+A skill is a directory under the configured skills root containing a
+``SKILL.md`` file with YAML frontmatter (``name``, ``description``) followed by
+a Markdown body. Only the metadata is loaded at startup and injected into the
+system prompt; the body and any sibling resources (``scripts/``, ``references/``,
+``assets/``) are loaded by the agent on demand — the *progressive disclosure*
+pattern from the Open Skills specification (https://agentskills.io/specification).
+
+Discovery is intentionally lenient: malformed entries are logged and skipped so
+one broken skill does not prevent the agent from booting. It is also strictly
+read-only — no mkdir, no writes, no imports, no ``sys.path`` mutation — so an
+existing skills root in the user's filesystem (e.g. from an unrelated project)
+cannot be clobbered by the agent. Discovery itself only runs when the operator
+sets ``AGENT_SKILLS_DIR``; an unset value is a no-op, matching the opt-in
+semantics of ``AGENT_TOOLS_DIR``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+NAME_MAX_CHARS = 64
+DESCRIPTION_MAX_CHARS = 1024
+
+_FRONTMATTER_RE = re.compile(
+    r"\A---\s*\n(?P<body>.*?)\n---\s*(?:\n|\Z)", re.DOTALL
+)
+_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+SKILL_FILENAME = "SKILL.md"
+
+
+@dataclass(frozen=True)
+class SkillRef:
+    """Metadata for one discovered skill.
+
+    Attributes:
+        name: Validated skill name (matches ``[a-z0-9]+(?:-[a-z0-9]+)*``,
+            capped at ``NAME_MAX_CHARS``). Equal to the parent directory name.
+        description: Free-form description, capped at ``DESCRIPTION_MAX_CHARS``.
+        path: Absolute path to the skill's ``SKILL.md``.
+    """
+
+    name: str
+    description: str
+    path: Path
+
+
+def discover_skills(skills_dir: Path) -> list[SkillRef]:
+    """Walk ``skills_dir`` and return one ``SkillRef`` per valid skill.
+
+    Returns an empty list if the directory does not exist or contains no
+    valid skills. Skills are returned sorted by name for deterministic
+    prompt ordering across restarts.
+    """
+    if not skills_dir.exists() or not skills_dir.is_dir():
+        return []
+
+    refs: list[SkillRef] = []
+    for entry in sorted(skills_dir.iterdir()):
+        if not entry.is_dir():
+            continue
+        skill_md = entry / SKILL_FILENAME
+        if not skill_md.is_file():
+            logger.debug("skipping %s: no %s", entry, SKILL_FILENAME)
+            continue
+        ref = _parse_skill(skill_md)
+        if ref is not None:
+            refs.append(ref)
+    return refs
+
+
+def _parse_skill(skill_md: Path) -> SkillRef | None:
+    try:
+        text = skill_md.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("skill unreadable: %s (%s)", skill_md, exc)
+        return None
+
+    match = _FRONTMATTER_RE.match(text)
+    if match is None:
+        logger.warning("skill missing YAML frontmatter: %s", skill_md)
+        return None
+
+    try:
+        meta = yaml.safe_load(match.group("body")) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("skill frontmatter not valid YAML: %s (%s)", skill_md, exc)
+        return None
+
+    if not isinstance(meta, dict):
+        logger.warning("skill frontmatter is not a mapping: %s", skill_md)
+        return None
+
+    raw_name = meta.get("name")
+    raw_desc = meta.get("description")
+    if not isinstance(raw_name, str) or not raw_name.strip():
+        logger.warning("skill missing required 'name': %s", skill_md)
+        return None
+    if not isinstance(raw_desc, str) or not raw_desc.strip():
+        logger.warning("skill missing required 'description': %s", skill_md)
+        return None
+
+    name = raw_name.strip()[:NAME_MAX_CHARS]
+    description = raw_desc.strip()[:DESCRIPTION_MAX_CHARS]
+
+    if not _NAME_RE.match(name):
+        logger.warning(
+            "skill name %r is not spec-compliant (a-z, 0-9, hyphens; no leading/"
+            "trailing/consecutive hyphens): %s",
+            name, skill_md,
+        )
+        return None
+
+    parent = skill_md.parent.name
+    if name != parent:
+        logger.warning(
+            "skill name %r does not match parent directory %r: %s",
+            name, parent, skill_md,
+        )
+        return None
+
+    return SkillRef(name=name, description=description, path=skill_md)
+
+
+_PROGRESSIVE_DISCLOSURE_PREAMBLE = (
+    "## Skills\n"
+    "\n"
+    "You have access to specialized skills below. Each skill is a self-contained "
+    "capability stored on disk. Skills follow **progressive disclosure**: only "
+    "the name and description are loaded into this prompt. To activate a skill, "
+    "read its `SKILL.md` at the listed path — that loads the full instructions "
+    "into context. Skills may also bundle `scripts/`, `references/`, or "
+    "`assets/` alongside `SKILL.md`; load those on demand only when the task "
+    "requires them.\n"
+    "\n"
+    "Available skills:"
+)
+
+
+def format_skills_block(skills: list[SkillRef]) -> str | None:
+    """Render the system-prompt skills block, or ``None`` when no skills exist."""
+    if not skills:
+        return None
+    lines = [_PROGRESSIVE_DISCLOSURE_PREAMBLE]
+    for s in skills:
+        lines.append(f"- **{s.name}** (`{s.path}`): {s.description}")
+    return "\n".join(lines)

{agentlings-0.2.3 → agentlings-0.4.0}/src/agentlings/core/task.py

@@ -42,6 +42,7 @@ from agentlings.core.models import (
     TaskStarted,
 )
 from agentlings.core.prompt import build_system_prompt
+from agentlings.core.skills import SkillRef
 from agentlings.core.store import JournalStore, TaskJournal
 from agentlings.core.telemetry import get_meter, otel_span
 from agentlings.tools.registry import ToolRegistry
@@ -351,6 +352,7 @@ class TaskWorker:
         registry: TaskRegistry,
         context_lock: asyncio.Lock,
         memory_store: MemoryFileStore | None = None,
+        skills: list[SkillRef] | None = None,
     ) -> None:
         self._record = record
         self._config = config
@@ -361,6 +363,7 @@ class TaskWorker:
         self._registry = registry
         self._context_lock = context_lock
         self._memory_store = memory_store
+        self._skills = skills or []
 
     async def run(self) -> None:
         """Drive the task to a terminal state.
@@ -461,6 +464,7 @@ class TaskWorker:
             data_dir=self._config.agent_data_dir,
             injection_prompt=memory_config.injection_prompt if memory_config else None,
             token_budget=memory_config.token_budget if memory_config else 2000,
+            skills=self._skills,
         )
 
         async def _on_turn(turn: Any) -> None:
@@ -573,12 +577,14 @@ class TaskEngine:
         llm: BaseLLMClient,
         tools: ToolRegistry,
         memory_store: MemoryFileStore | None = None,
+        skills: list[SkillRef] | None = None,
     ) -> None:
         self._config = config
         self._store = store
         self._llm = llm
         self._tools = tools
         self._memory_store = memory_store
+        self._skills = skills or []
         self._registry = TaskRegistry()
         self._context_locks: dict[str, asyncio.Lock] = {}
         self._context_locks_guard = asyncio.Lock()
@@ -689,6 +695,7 @@ class TaskEngine:
             registry=self._registry,
             context_lock=ctx_lock,
             memory_store=self._memory_store,
+            skills=self._skills,
         )
         asyncio_task = asyncio.create_task(worker.run(), name=f"task:{task_id}")
         self._workers[task_id] = asyncio_task