file-handler
Persist, fetch, and search local artifacts produced by skills under a predictable `.skillz/<type>/<slug>` tree. Use whenever a skill needs to save scratch files, plans, notes, or other working artifacts to disk and look them up again in a later turn — for example when a user says "save this as <slug>", "where did we save the <type>", "find the <slug> we saved", or any time another skill in this repo references "the file-handler". Wraps a single dependency-free Bash script (`scripts/skillz.sh`) that exposes `save_file`, `get_file`, and `search_files` (titles + body grep). All other skills should delegate to this skill instead of inventing their own on-disk layout. Do NOT use for source code edits, version-controlled files, or anything that belongs in the project tree — this is for skill artifacts, not application files.
How do I install this agent skill?
npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill file-handlerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a well-secured utility for local artifact storage. It implements strict validation on file and directory names to prevent path traversal and command injection, and it correctly scopes its operations to a local storage root.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
file-handler
One on-disk convention for every skill in this repo:
.skillz/
└── <type>/
└── <slug>
<type> groups artifacts by purpose (note, plan, draft, log,
…). <slug> is the filename. Both are validated — no path separators,
no .., no leading dots — so a skill can hand a user-supplied slug
straight through without sanitizing.
How to use this skill
When another skill needs to save or load a working file, shell out to
scripts/skillz.sh. Three subcommands cover the surface area:
# write content to .skillz/<type>/<slug>
scripts/skillz.sh save_file note todo "things to do"
# write stdin (preferred for multi-line content)
some_command | scripts/skillz.sh save_file plan release-cut
# read it back
scripts/skillz.sh get_file note todo
# search by title and body, optionally narrowed to a type
scripts/skillz.sh search_files todo
scripts/skillz.sh search_files release --type plan
save_file echoes the resolved path on success so callers can quote
it back to the user. get_file and search_files exit 1 when the
target / matches don't exist, so a skill can branch on ||.
Storage root
By default the tree lives at $PWD/.skillz. Override with SKILLZ_DIR
when you want a session-scoped or repo-scoped location:
SKILLZ_DIR="$HOME/.local/share/skillz" scripts/skillz.sh save_file note hello "hi"
Add .skillz/ to the repo's .gitignore if these artifacts shouldn't
be committed.
Conventions for callers
- Pick a type once and reuse it. Don't invent a new
<type>per artifact — types are buckets (note,plan,draft,log,transcript). Slugs are the unique part. - Slugs are ASCII filename-safe. Allowed:
[A-Za-z0-9._-](letters, digits, dot, underscore, hyphen — kebab-case is the preferred style, but dots for extensions and uppercase are accepted). Anything else gets rejected with exit 2. - No extension is required, but adding one (
.md,.txt,.json) helps when a user opens the file directly. - Prefer stdin over the inline content arg for anything multi-line — quoting gets fragile fast.
- Don't write through this skill for tracked source files. This is for skill scratch space, not the project tree.
Subcommand reference
save_file <type> <slug> [content]
Writes to .skillz/<type>/<slug>. If content is omitted, reads from
stdin. Parent directories are created on demand. Prints the resolved
path. Exit 2 on bad args.
get_file <type> <slug>
Prints .skillz/<type>/<slug> to stdout. Exit 1 if the file is
missing, exit 2 on bad args.
search_files <query> [--type <type>]
Two-pass search:
- Titles — case-insensitive
find -iname "*<query>*"across the storage root (or one type if--typeis supplied). - Bodies —
grep -rInfor the same query against the same scope. Binary files are skipped.
Output is sectioned (## titles then ## bodies); body hits are in
the standard <path>:<line>:<text> form so editors can jump to them.
Exit 1 when neither pass finds anything.
Why a single skill for this
Without a shared convention, each skill that needs to persist working
state ends up inventing its own (~/.cache/<skill>/, /tmp/<skill>-*,
a hidden file in $PWD, …). That fragments where users go to find
their stuff and makes cross-skill workflows harder ("the plan we drafted
last turn"). Centralizing on .skillz/<type>/<slug> plus three verbs
keeps the rest of the toolkit tiny.
When NOT to use this skill
- Application code, configs, or anything tracked in git. Edit those in place — this skill is for skill scratch space.
- Secrets.
.skillz/is plaintext on local disk. Use a secret manager (1Password, Bitwarden, age) instead. - Cross-machine sync. Files live on the local filesystem only. If you need them elsewhere, copy them out by hand or commit deliberately.
- Large binaries. The body-grep pass skips binary files, but the storage layout isn't tuned for big artifacts.
Gotchas
SKILLZ_DIRis captured at invocation, not export-once. Each shell-out re-resolves it, so changing the env between calls changes the storage root.- Slug validation rejects spaces. Pass
release-cut, notrelease cut. The regex is documented above. - Body grep uses fixed-string matching (
grep -F). Special characters (.,*,[) are matched literally. That's deliberate — users searching forv1.2.3get exactly what they typed, not a regex. - No locking. Two skills writing the same
<type>/<slug>concurrently will race; last writer wins. Use distinct slugs for parallel work.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/paulnsorensen/skillz-that-grillz/file-handler">View file-handler on skillZs</a>