diff --git a/hackmd-cli/SKILL.md b/hackmd-cli/SKILL.md
index d1f8ed4..66f2975 100644
--- a/hackmd-cli/SKILL.md
+++ b/hackmd-cli/SKILL.md
@@ -129,11 +129,14 @@ All list commands support:
 ### Sync local file to HackMD
 
 ```bash
-# Create new note from file
+# Create new note from file and verify
 cat doc.md | hackmd-cli notes create --title="My Doc"
+# Confirm creation by retrieving the note
+hackmd-cli notes --filter=title="My Doc"
 
-# Update existing note from file
+# Update existing note from file and verify
 cat doc.md | hackmd-cli notes update --noteId=<id>
+hackmd-cli export --noteId=<id> | head -5
 ```
 
 ### Export note to local file
@@ -153,3 +156,13 @@ hackmd-cli notes --output=json | jq '.[] | .id'
 ```bash
 hackmd-cli notes --filter=title=README
 ```
+
+## Error Handling
+
+Common errors and fixes:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Unauthorized` | Invalid or expired token | Re-run `hackmd-cli login` or update `HMD_API_ACCESS_TOKEN` |
+| `Not Found` | Wrong `noteId` or `teamPath` | Verify the ID with `hackmd-cli notes` or `hackmd-cli teams` |
+| `Forbidden` | Insufficient permissions | Check note permissions with `hackmd-cli notes --noteId=<id> -x` |
diff --git a/pr_description.md b/pr_description.md
new file mode 100644
index 0000000..d79daa2
--- /dev/null
+++ b/pr_description.md
@@ -0,0 +1,27 @@
+Hullo @hackmdio 👋
+
+I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after:
+
+| Skill | Before | After | Change |
+|-------|--------|-------|--------|
+| hackmd-cli | 94% | 100% | +6% |
+
+![Score Card](score_card.png)
+
+<details>
+<summary>Changes summary</summary>
+
+The `hackmd-cli` skill was already well-crafted (94%) — the only dimension below perfect was **workflow_clarity** (2/3). The changes are minimal and targeted:
+
+- **Added verification steps** to the "Sync local file to HackMD" workflow so users can confirm operations succeeded (e.g., retrieving the note after creation, previewing content after update)
+- **Added an Error Handling section** with a table covering common failure scenarios (`Unauthorized`, `Not Found`, `Forbidden`) and their fixes — giving users a clear troubleshooting path
+
+These two additions moved the content score from 88% to 100%, with workflow_clarity improving from 2/3 to 3/3.
+
+</details>
+
+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 - [@popey](https://github.com/popey) - if you hit any snags.
+
+Thanks in advance 🙏