Skip to content

Project instructions and skills

Beyond the base system prompt, Wallah hands the model two kinds of project-aware context, both re-discovered just before every turn so edits take effect mid-session without a restart.

Project instructions (AGENTS.md / CLAUDE.md)

Project instructions are gathered from two places and concatenated into a <project_context> block appended to the system prompt, each file wrapped in <project_instructions path="..."> so the model sees where it came from:

  • A prompts directory (default ~/.config/wallah/prompts, overridable with agent.set_prompts_dir). Its top-level AGENTS.md applies everywhere, and a per-project <project>/AGENTS.md applies only to that project. The project name is the same identity used for sessions (derived from git remotes, with aliases), so shared instructions can live outside any repository.
  • The working-directory chain: walking from the current directory up to the filesystem root, the AGENTS.md in each directory (or its CLAUDE.md when no AGENTS.md is present). This is where a repository's own checked-in AGENTS.md is picked up.

Empty files are ignored, and the file nearest the working directory takes precedence (it renders last). Relative markdown links inside a file are rewritten to absolute paths anchored at that file's directory, so a link like [COMMITS.md](COMMITS.md) still resolves once the text is in the model's context.

Skills (SKILL.md)

Skills follow Anthropic's Agent Skills convention: a directory containing a SKILL.md whose YAML frontmatter names the skill and describes when to use it.

---
name: pdf-fill
description: Fill in and flatten PDF form fields. Use when the user provides a
  fillable PDF and values to enter.
allowed-tools: [read, write, bash]
---

# Filling PDF forms

...step-by-step instructions the model reads on demand...

Skills are discovered from skills/ subdirectories, lowest to highest precedence: ~/.config/wallah/prompts/skills/*/, each project's <project>/skills/*/, then any roots you register from config.lua. Individual SKILL.md files can also be named directly:

agent.on('reconfigure', function()
  -- Directories whose immediate subdirectories each hold a SKILL.md.
  agent.add_skill_dirs { '~/skills', './.wallah/skills' }
  -- Or point at individual SKILL.md files.
  agent.add_skill_files { '~/skills/pdf-fill/SKILL.md' }
end)

agent.add_skill_dirs and agent.add_skill_files are called from a reconfigure handler, which fires at startup and on /reload.

Only each skill's name, description, and path are injected into the system prompt, as an <available_skills> catalog. The model reads the SKILL.md at that path on demand to load the full instructions (progressive disclosure), so a large skill costs nothing in tokens until it is actually used. For a directory-discovered skill the directory name is authoritative; a nonconformant name or an over-long description still loads but is reported as a warning, and skills sharing a name are deduped keeping the highest-precedence one.