feat(s040): skills: parser, sources, registry with index rows and watchers, the three tools, the prompt index, the /skills page, three bundled skills

SKILL.md parsed to the agentskills.io specification with Trinity's keys under trinity:; three
roots in precedence order with a per-file manifest check; a GenServer over ETS that scans at
boot, writes the index rows on the first read, keeps statuses and versions across rescans,
and watches the roots (inotify, polling without inotifywait); skills_list, skill_view and
skill_file (a symlink-resolving jail) as reads; the index in the context tier under 033's
338-token reserve; conditional activation by registered tools and toolsets; /skills with
badges, view, enable, disable, reindex and the load errors; mix trinity.skills.reindex;
VERSIONS rows for yaml_elixir and file_system.

Signed-off-by: Ayla Croft <aylacroft@proton.me>

Author: HackTuah

VERSIONS.md

@@ -130,6 +130,8 @@ never pin a version hex marks as retired or vulnerable.
 |---|---|---|---|
 | `muontrap` | ~> 2.0 | ✅ in `mix.lock` | The shell tool's process wrapper (`Trinity.Tools.Shell.Run`, Slice 022): a C port, SIGTERM then SIGKILL, the child dies with the port. Read against 2.0.0 at Slice 022: `cmd/3` takes `:timeout` (SIGTERM at expiry, `:timeout` as the status), `:delay_to_sigkill`, `:cd`, `:env`, optional cgroup v2 limits. ⚠️ POSIX only: declared in mix.exs on a Unix host alone; the shell tool is unavailable on Windows (NOTES.md, the Windows decision). |
 | `floki` | ~> 0.38 | ✅ in `mix.lock` | HTML to text for `web_fetch` (Slice 022): script, style, nav, header, footer and aside dropped, the body's text taken. |
+| `yaml_elixir` | ~> 2.12 | ✅ in `mix.lock` | SKILL.md frontmatter (`Trinity.Skills.Parser`, Slice 040), over `yamerl` 0.10.0. Was in the lock as sobelow's dependency; declared at 040. Checked against hex.pm 2026-09-21: 2.12.2 (2026-05-30). |
+| `file_system` | ~> 1.1 | ✅ in `mix.lock` | The skill roots' watcher (`Trinity.Skills.Registry`, Slice 040): inotify on Linux (needs the `inotifywait` executable; polls once a second without it), fsevents on macOS, the Windows backend there. Was in the lock as phoenix_live_reload's dependency; declared at 040. Checked against hex.pm 2026-09-21: 1.1.1 (2025-09-08). |
 | `luerl (+ sandbox)` | latest | 🔍 not a single package | Slice 110 only. Two packages, so no single lock key. |
 | `burrito` | ~> 1.6 | ✅ in `mix.lock` | ⚠️ ERTS availability drives the OTP pin, and Slice 000 measured it: only the OTP 28 line is fetchable for macOS and Linux. Corrected 2026-09-05: this row previously read `~> 1.5 / 1.5.0 ✅`; that mark was not measured. Added at Slice 001. |
 | `ex_tauri` | ~> 0.2 | ✅ in `mix.lock` | ⚠️ Declares `otp_release: "~> 27.0"`, and Slice 000's probe refutes the reason it gives: OTP 28 macOS universal returns 200 and OTP 27 returns 404. Whether it runs on the pinned OTP is Slice 001's first measurement. ⚠️ 439 downloads all-time, so the ADR-0004 fallback matrix carries real weight. |

config/config.exs

@@ -75,6 +75,10 @@ config :trinity, :tools,
     Trinity.Tools.SessionSearch,
     # Slice 032: hybrid recall over semantic memories and past messages.
     Trinity.Tools.Recall,
+    # Slice 040: the skills' progressive disclosure.
+    Trinity.Skills.Tools.List,
+    Trinity.Skills.Tools.View,
+    Trinity.Skills.Tools.File,
     # Slice 030: the always-on memory tiers.
     Trinity.Tools.Memory,
     Trinity.Tools.Shell.Run
@@ -84,9 +88,16 @@ config :trinity, :tools,
     web: ["web_fetch", "web_search"],
     shell: ["shell"],
     # Slice 031: search over past conversations.
-    memory: ["session_search", "recall", "memory"]
+    memory: ["session_search", "recall", "memory"],
+    # Slice 040: the skill tools.
+    skills: ["skills_list", "skill_view", "skill_file"]
   }
 
+# Slice 040: the skill roots. `user_dir:` and `bundled_dir:` default to the data directory's
+# `skills` and `priv/skills`; `watch: false` turns the filesystem watchers off (the reindex
+# button and `mix trinity.skills.reindex` remain); `index_tokens:` caps the prompt's index.
+config :trinity, :skills, watch: true, index_tokens: 338
+
 # Slice 022: the filesystem roots beside the data directory (always a root) and the session's
 # working directory. Empty here; config/runtime.exs reads TRINITY_FS_ROOTS (colon-separated).
 config :trinity, :fs, roots: []

config/test.exs

@@ -29,6 +29,10 @@ config :trinity, :tools,
     Trinity.Tools.SessionSearch,
     # Slice 032: hybrid recall.
     Trinity.Tools.Recall,
+    # Slice 040: the skills' progressive disclosure.
+    Trinity.Skills.Tools.List,
+    Trinity.Skills.Tools.View,
+    Trinity.Skills.Tools.File,
     # Slice 030: the always-on memory tiers.
     Trinity.Tools.Memory,
     Trinity.Tools.Shell.Run
@@ -39,7 +43,9 @@ config :trinity, :tools,
     web: ["web_fetch", "web_search"],
     shell: ["shell"],
     # Slice 031: search over past conversations.
-    memory: ["session_search", "recall", "memory"]
+    memory: ["session_search", "recall", "memory"],
+    # Slice 040: the skill tools.
+    skills: ["skills_list", "skill_view", "skill_file"]
   },
   timeout_ms: 2_000
 
@@ -171,3 +177,11 @@ config :trinity, :receipts, keys_dir: Path.expand("../tmp/test_keys", __DIR__)
 # Slice 032: the suite embeds with the deterministic fake; nothing leaves the machine and no
 # model is needed.
 config :trinity, :memory, embedder: :fake, observer: false
+
+# Slice 040: the suite's skill roots are fixtures; the user root is a directory a test may
+# point elsewhere with `Application.put_env` and a rescan.
+config :trinity, :skills,
+  bundled_dir: Path.expand("../test/support/fixtures/skills/bundled", __DIR__),
+  user_dir: Path.expand("../test/support/fixtures/skills/user", __DIR__),
+  watch: true,
+  index_tokens: 338

lib/mix/tasks/trinity.skills.reindex.ex

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Mix.Tasks.Trinity.Skills.Reindex do
+  @shortdoc "Rescans the skill roots and rewrites the skills index"
+
+  @moduledoc """
+  Slice 040. Scans the user root (`<data dir>/skills`) and the bundled root (`priv/skills`),
+  rewrites the `skills` table from what is on disk (statuses kept), and prints every skill
+  with its source, version and status, then every directory that did not load and why.
+
+      mix trinity.skills.reindex
+  """
+  use Boundary, classify_to: Trinity
+  use Mix.Task
+
+  @impl Mix.Task
+  def run(_argv) do
+    Mix.Task.run("app.start")
+    {us, :ok} = :timer.tc(fn -> Trinity.Skills.rescan() end)
+    skills = Trinity.Skills.list()
+    Mix.shell().info("reindexed #{length(skills)} skills in #{div(us, 1000)} ms")
+
+    for s <- skills,
+        do:
+          Mix.shell().info(
+            "  #{s.name}  #{s.source}/#{s.scope}  v#{s.version}  #{s.status}  #{s.path}"
+          )
+
+    for e <- Trinity.Skills.Registry.errors(),
+        do: Mix.shell().info("  not loaded: #{e.dir} (#{e.source}): #{inspect(e.reason)}")
+  end
+end

lib/trinity.ex

@@ -29,6 +29,7 @@ defmodule Trinity do
         Personas,
         Context,
         Context.AgentsMd,
+        Context.SkillsIndex,
         Archive,
         Archive.Layout,
         Archive.Manifest,
@@ -50,6 +51,10 @@ defmodule Trinity do
         Permissions.Approval,
         Permissions.Rule,
         Effects,
+        Skills,
+        Skills.Skill,
+        Skills.Registry,
+        Skills.Sources,
         CorePolicy,
         Receipts,
         Receipts.Receipt,

lib/trinity/application.ex

@@ -54,6 +54,9 @@ defmodule Trinity.Application do
           Trinity.Tools.Supervisor,
           # Slice 021: approval requests and their decisions, with pending rows reloaded.
           Trinity.Permissions.Gate,
+          # Slice 040: the skills index, scanned from its roots and watched; after the tools
+          # (conditional activation asks which exist) and before the sessions that read it.
+          Trinity.Skills.Registry,
           Trinity.Sessions.Supervisor
         ] ++
         Trinity.Smoke.probe(Trinity.Smoke.argv()) ++

lib/trinity/context.ex

@@ -6,5 +6,5 @@ defmodule Trinity.Context do
   content, read from the project root every turn, untrusted by provenance. `AgentsMd` is the
   first source; slice 040's skills index joins it in the same tier.
   """
-  use Boundary, deps: [Trinity], exports: [AgentsMd]
+  use Boundary, deps: [Trinity, Trinity.Skills], exports: [AgentsMd, SkillsIndex]
 end

lib/trinity/context/skills_index.ex

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.Context.SkillsIndex do
+  @moduledoc """
+  The skills index in the context tier (slice 040): the active skills for the session's
+  project, rendered by `Trinity.Skills.Index` under the prompt cap. Read every turn like the
+  AGENTS.md block beside it, so a skill added on disk is in the next turn.
+  """
+
+  alias Trinity.Skills.Index
+
+  @doc "The block for a project root (`nil` for none): `\"\"` when no skill is active."
+  @spec render(String.t() | nil) :: String.t()
+  def render(project_root) do
+    project_root
+    |> then(&Trinity.Skills.active(project_root: &1))
+    |> Index.render(Index.default_tokens())
+  end
+end

lib/trinity/sessions/session.ex

@@ -355,7 +355,14 @@ defmodule Trinity.Sessions.Session do
     tools = Trinity.Tools.to_llm_tools()
     history = Trinity.Sessions.history(id, limit: 500)
     # Slice 033: the project's AGENTS.md, read now, so a change is in this turn (live reload).
-    context = Trinity.Context.AgentsMd.render(session.project_root, session.project_root)
+    context =
+      [
+        Trinity.Context.AgentsMd.render(session.project_root, session.project_root),
+        # Slice 040: the skills index, under its own cap inside the same tier.
+        Trinity.Context.SkillsIndex.render(session.project_root)
+      ]
+      |> Enum.reject(&(&1 == ""))
+      |> Enum.join("\n\n")
 
     # Slice 032: what the semantic tier and past conversations hold about the latest user
     # message, fused and capped; "" when there is no persona or nothing relevant.

lib/trinity/skills.ex

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.Skills do
+  @moduledoc """
+  Procedural memory (slice 040, ADR-0006): skills are directories with a `SKILL.md` in the
+  agentskills.io format, found under three roots in precedence order (a project's
+  `.trinity/skills`, the data directory's `skills`, the bundled `priv/skills`), parsed into
+  `Trinity.Skills.Skill`, indexed in the `skills` table and held by `Trinity.Skills.Registry`,
+  and shown to the model by progressive disclosure: the index in the prompt, the body on
+  `skill_view`, a reference file on `skill_file`. The filesystem is canonical; the table is
+  an index a reindex rebuilds. Nothing here writes a skill: that is slice 041's.
+
+  Depends on Tools because conditional activation asks the registry which tools and
+  toolsets exist, and because the three skill tools implement `Trinity.Tools.Tool`; Tools
+  never depends on Skills.
+  """
+  use Boundary,
+    deps: [Trinity, Trinity.Tools, Trinity.Memory],
+    exports: [Skill, Parser, Sources, Registry, Row, Index, Tools.List, Tools.View, Tools.File]
+
+  alias Trinity.Skills.Registry
+
+  @doc "The effective skills (one per name, by precedence); `project_root:` adds a project's."
+  @spec list(keyword()) :: [Trinity.Skills.Skill.t()]
+  defdelegate list(opts \\ []), to: Registry
+
+  @doc "The skills the model may see now: active, and their requirements met."
+  @spec active(keyword()) :: [Trinity.Skills.Skill.t()]
+  defdelegate active(opts \\ []), to: Registry
+
+  @doc "A skill by name, among the effective ones."
+  @spec get(String.t(), keyword()) :: Trinity.Skills.Skill.t() | nil
+  defdelegate get(name, opts \\ []), to: Registry
+
+  @doc "Rescans every root and rewrites the index."
+  @spec rescan() :: :ok
+  defdelegate rescan(), to: Registry
+
+  @doc "Enables or disables a skill by name and source; persisted in the index."
+  @spec set_status(String.t(), String.t(), String.t()) :: :ok | {:error, term()}
+  defdelegate set_status(name, source, status), to: Registry
+end