Document dynamic skill metadata callbacks

- writing-skills.md: add UI metadata section, update examples
- ALEXCLAW_ARCHITECTURE.md: describe skill UI metadata system
- changelog: add dynamic skill metadata entry

Author: thatsme

ALEXCLAW_ARCHITECTURE.md

@@ -343,6 +343,8 @@ AlexClaw supports multi-node BEAM clustering. Each node runs its own sequential
 
 Skills are Elixir modules implementing the `AlexClaw.Skill` behaviour (`run/1`, optional `description/0`, `routes/0`, `permissions/0`, `version/0`, `external/0`). Skills return `{:ok, result, :branch}` for conditional routing or `{:ok, result}` for backward compatibility. Registered in `AlexClaw.Workflows.SkillRegistry` with routes and external flag stored in ETS alongside permissions.
 
+Skills also declare **UI metadata** via optional callbacks (`step_fields/0`, `config_hint/0`, `config_scaffold/0`, `config_presets/0`, `prompt_presets/0`, `config_help/0`, `prompt_help/0`). The workflow step editor reads these via `SkillRegistry.get_skill_meta/1` to dynamically render only the fields a skill needs. Skills that don't use LLM (scrapers, notifiers, shell) declare `step_fields: [:config]` — no LLM tier, provider, or prompt template shown. Zero hardcoded skill metadata in the LiveView.
+
 Skills that fetch data from external sources declare `def external, do: true`. The workflow executor auto-sanitizes output from external skills through `AlexClaw.ContentSanitizer` (7-layer heuristic pipeline). Dynamic skills are AST-scanned at load time — undeclared HTTP/socket calls are rejected.
 
 | Skill | Module | Tier | Description |

docs/reference/changelog.md

@@ -9,7 +9,8 @@
 - **Bug fix** — `duplicate_workflow` now copies `input_from` and `routes` fields
 - **Docker naming** — services renamed to `alexclaw-prod`, `db-prod`, `db-test` for clarity
 - **Makefile** — quiet test builds, auto-teardown after tests, `test-down` target
-- **Docs** — README, INSTALLATION, architecture, and readthedocs pages updated
+- **Dynamic skill metadata** — skills declare their own UI fields via 7 new optional callbacks (`step_fields`, `config_hint`, `config_scaffold`, `config_presets`, `prompt_presets`, `config_help`, `prompt_help`). Step editor renders dynamically — zero hardcoded skill knowledge in the LiveView
+- **Docs** — README, INSTALLATION, architecture, writing-skills, and readthedocs pages updated
 
 ## v0.3.13 — MCP Server (2026-03-27)
 

docs/skills/writing-skills.md

@@ -29,6 +29,13 @@ defmodule AlexClaw.Skills.Dynamic.MySkill do
 
   @impl true
   def routes, do: [:on_success, :on_error]
+
+  # UI metadata — controls which fields appear in the step editor
+  @impl true
+  def step_fields, do: [:llm_tier, :llm_model, :prompt_template, :config]
+
+  @impl true
+  def config_hint, do: ~s|{"option": "value"}|
 end
 ```
 
@@ -40,6 +47,8 @@ end
 
 ## Optional Callbacks
 
+### Core
+
 | Callback | Default | Description |
 |---|---|---|
 | `description/0` | `"<name> skill"` | Human-readable description |
@@ -48,6 +57,20 @@ end
 | `version/0` | `"1.0.0"` | Skill version string |
 | `external/0` | `false` | Whether the skill fetches data from external sources |
 
+### UI Metadata
+
+These callbacks control how the workflow step editor renders when your skill is selected. If not declared, all fields are shown (backward compatible).
+
+| Callback | Default | Description |
+|---|---|---|
+| `step_fields/0` | `[:llm_tier, :llm_model, :prompt_template, :config]` | Which optional fields to show in the step editor. Use `[:config]` for skills that don't use LLM. Use `[]` for skills with no configurable fields. |
+| `config_hint/0` | `""` | Placeholder text shown in the config JSON textarea |
+| `config_scaffold/0` | `%{}` | Default config map pre-filled when adding a new step |
+| `config_presets/0` | `%{}` | Named config templates shown as buttons (e.g. `%{"GET" => %{"method" => "GET"}}`) |
+| `prompt_presets/0` | `%{}` | Named prompt templates shown as buttons (e.g. `%{"Summarize" => "Summarize:\n\n{input}"}`) |
+| `config_help/0` | `"Skill-specific parameters as JSON."` | Help text shown as tooltip on the config field |
+| `prompt_help/0` | `"Template sent to the LLM. Use {input} for previous step output."` | Help text shown as tooltip on the prompt field |
+
 ## The `args` Map
 
 Every skill receives a map with these keys:
@@ -184,8 +207,50 @@ defmodule AlexClaw.Skills.Dynamic.UrlHealthCheck do
   @impl true
   def routes, do: [:on_success, :on_error]
 
+  # UI metadata — step editor shows only config, no LLM fields
+  @impl true
+  def step_fields, do: [:config]
+
+  @impl true
+  def config_hint, do: ~s|{"timeout": 5000}|
+
+  @impl true
+  def config_scaffold, do: %{"timeout" => 5000}
+
+  @impl true
+  def config_help, do: "timeout: HTTP timeout in ms per URL (default 5000). Input: newline-separated URLs."
+
   defp parse_urls(input) when is_binary(input), do: String.split(input, "\n", trim: true)
   defp parse_urls(input) when is_list(input), do: input
   defp parse_urls(_), do: []
 end
 ```
+
+## Example: Scraper (No LLM)
+
+A skill that scrapes data and embeds it — no LLM fields needed in the step editor:
+
+```elixir
+defmodule AlexClaw.Skills.Dynamic.HexdocsScraper do
+  @behaviour AlexClaw.Skill
+
+  @impl true
+  def step_fields, do: [:config]
+
+  @impl true
+  def config_hint, do: ~s|{"packages": ["phoenix", "ecto"]}|
+
+  @impl true
+  def config_scaffold, do: %{"packages" => []}
+
+  @impl true
+  def config_help, do: "packages: list of Hex package names to scrape and index."
+
+  @impl true
+  def run(args) do
+    # ... scraping logic
+  end
+end
+```
+
+The step editor will show only the Config (JSON) field — no LLM Tier, Provider, or Prompt Template.