# watcher-runner-filesystem

> Run, smoke-test, and debug the Bronze-tier filesystem watcher (Python) that monitors a local drop folder and creates markdown action items inside the Obsidian vault's /Needs_Action folder. This skill should be used when the user asks to "run the watcher", "start the filesystem watcher", "debug why Needs_Action is not updating", "watch a folder for new files", "test the watcher end-to-end", or when Claude needs to validate the Perception layer of Hackathon Zero without Gmail/OAuth. Trigger phrases include: "filesystem watcher", "drop folder", "watchdog", "watcher logs", "no files appearing in Needs_Action", "uv run watcher", and "watchdog observer".

- Author: Ashna Ghazanfar
- Repository: Syedaashnaghazanfar/hackathon-0
- Version: 20260209022036
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/Syedaashnaghazanfar/hackathon-0
- Web: https://mule.run/skillshub/@@Syedaashnaghazanfar/hackathon-0~watcher-runner-filesystem:20260209022036

---

---
name: watcher-runner-filesystem
description: >
  Run, smoke-test, and debug the Bronze-tier filesystem watcher (Python) that monitors a local drop folder
  and creates markdown action items inside the Obsidian vault's /Needs_Action folder.
  This skill should be used when the user asks to "run the watcher", "start the filesystem watcher",
  "debug why Needs_Action is not updating", "watch a folder for new files", "test the watcher end-to-end",
  or when Claude needs to validate the Perception layer of Hackathon Zero without Gmail/OAuth.
  Trigger phrases include: "filesystem watcher", "drop folder", "watchdog", "watcher logs", "no files appearing in Needs_Action",
  "uv run watcher", and "watchdog observer".
---

# Watcher Runner (Filesystem)

Start and validate the Bronze-tier watcher that turns local file drops into `Needs_Action/*.md` items.

## Assumptions

- Project code lives under `MY-AI-EMPLOYEE/` (user-provided convention).
- The watcher script exists in that project (commonly `watchers/filesystem_watcher.py` or similar).
- The watcher needs two paths:
  - Vault root path
  - Watched drop folder path

If any of these are unknown, stop and ask for the paths.

## Run workflow

1. Locate the watcher entrypoint.
2. Verify Python environment setup (uv/venv) and dependencies.
3. Run watcher in foreground first (for visible logs).
4. Trigger a file creation in the watched folder.
5. Confirm a new action item appears in `Needs_Action/`.

## Debug workflow

1. Confirm the watcher process is running.
2. Confirm filesystem events are firing (some environments require polling).
3. Confirm vault path is correct and writable.
4. Confirm watcher is writing `.md` action files (not only copying binaries).

## Resources

- Reference: `references/runbook.md`
- Example smoke test script: `scripts/create_test_drop.py`
- Examples: `examples.md`