feat: improve agent-filesystem skill score (72% → 100%) (#19)

Hey @rowantrollope 👋

I ran your skills through `tessl skill review` at work and found some targeted improvements for the `agent-filesystem` skill. Here's the full before/after:

| Skill | Before | After | Change |
|-------|--------|-------|--------|
| agent-filesystem | 72% | 100% | +28% |
| codex-settings-sync | 76% | 76% | — |
| agent-filesystem (plugin) | 90% | 90% | — |
| team-rules (example) | 97% | 97% | — |
| team-prd (example) | 90% | 90% | — |

<details>
<summary>What changed in <code>agent-filesystem</code></summary>

- **Expanded frontmatter description** with an explicit "Use when" clause covering persistent shared storage, saving/restoring workspace state, and coordinating file access across agents and machines
- **Added natural trigger terms** like "persistent shared storage", "checkpoint", "shared filesystems", and "fork workspaces" so agents can better match user intent to this skill
- **Enriched the use-case list** with clearer, more specific scenarios (surviving sessions/machines, Redis-backed directories, parallel experiments)
- **Added verification steps** after key CLI operations (`afs ws list`, `afs status`, `afs cp list`) so agents get feedback loops instead of fire-and-forget commands
- **Added a "Further Reading" section** pointing to `docs/guides/agent-filesystem.md`, `docs/reference/cli.md`, and `docs/reference/mcp.md` for progressive disclosure

</details>

I also stress-tested your `agent-filesystem` skill against a few real-world task evals and it held up really well on workspace checkpoint-and-restore cycles across multi-agent sessions. Kudos for that.

Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch — just saw room for improvement and wanted to contribute.

Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me — [@yogesh-tessl](https://github.com/yogesh-tessl) — if you hit any snags.

Thanks in advance 🙏

Co-authored-by: Yogesh Rao <yogesh-tessl@users.noreply.github.com>

Author: yogesh-tessl

skills/agent-filesystem/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-filesystem
-description: Persistent Redis-backed workspaces for agents. Use via `afs mcp`, the `afs` CLI, sync mode, live mounts, and explicit checkpoints.
+description: "Use when agents need persistent shared storage, when saving or restoring workspace state, or when coordinating file access across multiple agents and machines. Creates Redis-backed workspaces, checkpoints and restores agent state, mounts shared filesystems locally, searches workspace contents, and forks workspaces for parallel work."
 ---
 
 # Agent Filesystem
@@ -12,10 +12,11 @@ explicit checkpoints and easy movement between MCP, sync mode, and live mounts.
 ## When to Use This Skill
 
 **Use for:**
-- Persistent agent workspaces
-- Code or docs that should live in a normal directory
-- Shared notes/config/state that benefit from checkpoints and forks
-- Searchable workspaces where `afs fs grep` or MCP file tools are useful
+- Persistent agent workspaces that survive across sessions and machines
+- Code, docs, or shared state that should live in a normal directory backed by Redis
+- Saving and restoring workspace snapshots with explicit checkpoints
+- Searching workspace contents with `afs fs grep` or MCP file tools
+- Forking a workspace to run parallel experiments without losing the original
 
 **Avoid for:**
 - Large build output, media, or disposable artifacts
@@ -46,11 +47,13 @@ workspace exposed directly as a mount rather than through the sync daemon.
 ```bash
 ./afs ws create my-project
 ./afs ws import my-project ./existing-dir
+./afs ws list                          # verify the workspace exists
 ```
 
 ### Start working locally
 ```bash
 ./afs ws mount my-project ~/my-project
+./afs status                           # verify the mount is active
 cd ~/my-project
 ```
 
@@ -63,13 +66,15 @@ cd ~/my-project
 ### Save and restore stable points
 ```bash
 ./afs cp create my-project before-refactor
-./afs cp list my-project
+./afs cp list my-project               # verify the checkpoint was saved
 ./afs cp restore my-project before-refactor
+./afs cp list my-project               # confirm the restore completed
 ```
 
 ### Fork work for a second line of effort
 ```bash
 ./afs ws fork my-project my-project-experiment
+./afs ws list                          # verify the fork appears
 ```
 
 ## Key Points
@@ -81,3 +86,9 @@ cd ~/my-project
 - File edits change the live workspace immediately.
 - Create checkpoints explicitly when you want a restore point.
 - `.afsignore` controls what gets imported from an existing local directory.
+
+## Further Reading
+
+- `docs/guides/agent-filesystem.md` — agent-facing usage guide
+- `docs/reference/cli.md` — full CLI command reference
+- `docs/reference/mcp.md` — MCP tool reference for agent integrations