Initial changes: agent.rules and agent.skill extensionsHEADmain

panto-agent is a luarocks rock providing the agent.* extension suite
for pantograph's panto CLI:

- agent.rules: injects AGENTS.md/CLAUDE.md (AGENTS.md wins, never both)
  from the base agent dir, user config dir, and project root into the
  system prompt at session start. Also hooks std.read tool results to
  append rules files found between a read location and the project
  root, each injected at most once per session.

- agent.skill: discovers Agent Skills (SKILL.md with YAML frontmatter)
  across data/config/home/project skill dirs with later dirs shadowing
  earlier ones, and exposes them via an agent.skill tool whose enum and
  description are built from the surviving skills. The tool returns the
  skill's instructions with frontmatter stripped. Not registered when
  no skills are found.

Includes a rockspec, README, and a panto-runnable self-check
(_selfcheck.lua, underscore-prefixed so panto's directory scan skips
it). Sources live under panto-agent/ so require works the same
installed or from a checkout.

1 files changed, 69 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3bd4b57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# panto-agent
+
+The `agent.*` extension suite for [pantograph](https://github.com/travisp/pantograph)'s
+`panto` CLI: coding-agent conveniences packaged as a luarocks rock.
+
+## Extensions
+
+- **`agent.rules`** — at session start, injects the contents of `AGENTS.md`
+  (or `CLAUDE.md` when no `AGENTS.md` exists — never both) into the system
+  prompt, from each of: the base layer agent dir
+  (`${XDG_DATA_HOME:-~/.local/share}/panto/agent`), the user layer dir
+  (`${XDG_CONFIG_HOME:-~/.config}/panto`), and the project root (cwd).
+  Symlinks are resolved; each file becomes one system message headed
+  `context from <path>:`.
+
+  It also hooks `std.read` results (a `tool_result` event handler using
+  the writable `output` field): reading a file (or directory) below the
+  project root appends any `AGENTS.md`/`CLAUDE.md` found between the read
+  location and the root (root excluded — the system prompt covers it) to
+  the tool result as `---`-separated `context from <path>:` sections.
+  Each real file is injected at most once per session. The transcript
+  keeps the read's own output, with a `+ rules: <path>` line per attached
+  file below it.
+
+- **`agent.skill`** — an `agent.skill` tool for loading
+  [Agent Skills](https://agentskills.io) on demand. At activation it
+  discovers skills (subdirectories containing a `SKILL.md` with YAML
+  frontmatter) from, lowest priority first:
+  `${XDG_DATA_HOME:-~/.local/share}/panto/agent/skills`,
+  `${XDG_CONFIG_HOME:-~/.config}/panto/skills`, `~/.agent/skills`,
+  `<cwd>/.panto/skills`, and `<cwd>/.agent/skills`. The frontmatter
+  `name` (not the directory name) is the skill's identity; later
+  directories shadow same-named skills from earlier ones. Surviving
+  names and descriptions are baked into the tool's description and its
+  input schema's enum. Calling the tool returns the skill's `SKILL.md`
+  instructions (frontmatter stripped) behind a preamble that tells the
+  model to resolve the skill's relative paths against its directory.
+  With no skills discovered, the tool is not registered.
+
+## Install
+
+Via the rock (once published):
+
+```toml
+[extensions]
+rocks = ["panto-agent"]
+```
+
+Or as a local checkout:
+
+```toml
+[extensions]
+paths = ["/path/to/panto-agent"]
+```
+
+Individual extensions can be toggled with the usual policy globs, e.g.
+`deny = ["agent.rules"]`.
+
+## Development
+
+Run the self-check (needs `panto` for its embedded Lua + luv):
+
+```sh
+panto lua _selfcheck.lua
+```
+
+Layout note: the sources live under `panto-agent/` (matching the installed
+module tree) so `require` works identically installed and from a checkout;
+`_selfcheck.lua` is `_`-prefixed so panto's directory scan skips it.