Why a refresh button matters in skill discovery for GoWork

If you add a new skill directory and GoWork still does not show it, the short answer is this: the refresh button matters because it lets the user ask for re-indexing immediately. Without it, people are forced to guess whether they are still seeing a stale cache snapshot. With it, “maybe it will appear in a while” becomes a clear instruction: “I just changed the filesystem; rebuild discovery now.”

That distinction matters much more in an execution-oriented assistant than in an ordinary chat tool. A chatbot can merely say “this may be a cache issue.” But a system like OmniGoAI’s GoWork has to make skill routing, path resolution, and execution entry points verifiable, rebuildable, and recoverable. What looks like a small UI control is actually part of the machinery that decides whether the assistant can select the right skill and follow the right procedure.

If you already read Why a newly added skill may stay invisible until cache refresh in GoWork, why multi-step tasks need plans that persist across runs, and resume AI tasks after failure instead of restarting, this article answers the narrower product question: if discovery already has a cache TTL, why do you still want a manual refresh button?

The refresh button does not add discovery capability. It adds discovery timing control.

It is easy to say that if the scanner will eventually find the skill anyway, a refresh button is optional. But from the user’s perspective, the difference is huge.

Without a refresh button, the user must wait for cache expiry.
With a refresh button, the user can request a new scan right after making a change.
With a full rescan option, the system can also recover from root-path or traversal-scope changes.

So TTL solves system efficiency, while refresh solves user control. They are complementary, not interchangeable.

Why “just wait for cache expiry” feels bad in practice

Because it forces the user to wait in front of a system whose internal state is invisible.

When a new skill does not appear, users immediately start asking questions like these:

Did I put it in the wrong directory?
Is the UI still showing old cache?
Does the system already know about the change?
Should I restart the app?
Or is the skill file itself broken?

Most of those questions are not about the skill content. They are about whether discovery has acknowledged the change yet. A refresh button collapses that uncertainty into one actionable step: stop guessing and explicitly request re-indexing now.

Why execution-oriented assistants need this more than ordinary apps

Because the cost of being wrong is higher.

In a normal content app, a missing plugin card usually means one feature is temporarily unavailable. In an execution-oriented assistant, missing or stale skill discovery can affect:

whether the current request is routed to the right skill;
whether the assistant follows the intended workflow;
whether it reuses a known procedure or falls back to ad hoc exploration;
whether shared state resolves to the correct source tree.

In other words, the skill list is not a decorative menu. It is part of the routing layer for execution. If that layer still reflects an old index, planning, memory reuse, and downstream execution can drift.

Why a refresh button should not be treated as an advanced-user-only feature

Because adding and iterating on skills is itself a common workflow.

In a local AI assistant setup, people routinely do things like:

add a new skill directory;
edit SKILL.md metadata;
copy a skill from another repo;
move a skill back into a shared root;
verify that discovery sees the latest version.

If every one of those changes requires passive waiting, the product feels arbitrary: I already changed the files, but whether the system recognizes that change seems to depend on timing.

A refresh button changes that feeling into: I changed the files, and now I can immediately test whether discovery picked them up. That is not a tiny convenience. It is a major improvement in iteration speed and confidence.

From a product-design perspective, the refresh button restores cause-and-effect feedback

A usable system is not only functionally correct. It should also let users understand what happened because of what they just did.

Adding a skill is a clear user action, so people naturally expect a clear response:

I placed the directory.
I pressed refresh.
The system rescanned.
The skill either appeared, or the product told me what is still wrong.

If the explicit refresh step is missing, the causal chain breaks. The user changed the filesystem, but has no matching action that says “now rebuild what you know.” The result is a lot of restarting, waiting, and second-guessing. The core problem is not cache itself. It is the lack of an explicit entry point for user-driven re-indexing.

What kinds of mistakes does a refresh button prevent?

The biggest one is misclassifying “not discovered yet” as “already failed.”

A very common sequence looks like this:

the skill files are actually fine;
the path is correct;
the UI is still showing an old snapshot;
the user concludes the skill must be malformed and starts rewriting it.

That wastes time and often introduces new problems. With a refresh button, the troubleshooting order becomes much cleaner:

confirm the skill is in a directory the current GoWork build scans;
press refresh immediately;
if it still does not appear, consider a full rescan;
only then inspect SKILL.md or metadata issues.

That sequence stops many problems at the discovery layer before they turn into unnecessary skill rewrites.

Why this is also about path consistency, not only about UI visibility

Because stale or mixed discovery results do more than hide one card. They can make the system point to the wrong source.

The content-pipeline skill has a strict rule: shared state must always be read from D:/omnigoai/.claude/skills/content-pipeline/, not from whichever copy of the instructions happened to be nearby. The principle is simple: instruction copies may exist, but state truth must remain singular.

The same logic applies to discovery. One purpose of a refresh button is to let the user immediately rebuild the mapping between skill name, actual directory, and state location after a migration, copy, or path fix.

So the benefit is not only “make the skill appear.” It is also “make sure the system is now pointing at the latest and correct source.”

Why TTL alone is not enough, and refresh alone is not enough either

A healthy discovery system usually needs three layers:

TTL for stable everyday performance;
refresh for immediate feedback after a user change;
full rescan for root-level or traversal-level repairs.

Remove any one of them and the experience degrades:

TTL without refresh forces blind waiting;
refresh without TTL makes ordinary browsing heavier than necessary;
no full rescan means some discovery failures survive ordinary refresh forever.

That is why cache TTL, refresh controls, and global rescan should be treated as a coordinated discovery system rather than interchangeable toggles.

A practical rule of thumb: when should you refresh, and when should you rescan?

Scenario 1: You just added a new skill directory

Start with refresh. Most ordinary additions are solved at that level.

Scenario 2: You edited the skill title, description, or match scope

Again, start with refresh, because this is usually just metadata re-indexing.

Scenario 3: You changed the skill root, copy strategy, or mount strategy

Consider a full rescan earlier. The problem may be scan scope, not stale cache.

Scenario 4: The files are visible in the file manager but still absent in GoWork

Then inspect path semantics. File existence only proves the filesystem contains the skill. It does not prove the discovery scanner traversed and indexed it.

Why this small feature affects trust in the whole assistant system

Because what users really want to know is not whether a button is clickable. They want to know: is the system working from the change I just made?

If a new skill does not show up promptly, people start doubting broader state consistency:

is the UI still reading old cache?
is execution still bound to an older skill copy?
is the product still pointing at an outdated path?

A clear refresh entry turns that doubt into a verifiable flow: change, refresh, inspect result, continue troubleshooting if needed. In an execution-oriented assistant, that kind of determinism matters far more than the fact that background discovery would probably catch up later.

FAQ

FAQ 1: What should I do first when a new skill does not appear?

Do not rewrite the skill yet and do not restart the app first. Confirm the directory is correct, then press refresh and see whether discovery catches up.

FAQ 2: What is the practical difference between refresh and waiting for cache TTL?

TTL expiry is passive and system-driven. Refresh is active and user-driven. The former balances performance; the latter restores immediate control.

FAQ 3: Why can I see the skill in the file manager but not in GoWork?

Because file existence only proves the files are on disk. It does not prove the discovery scanner has traversed and indexed them. Common causes are stale cache or traversal limits in the current build.

FAQ 4: If one refresh does not help, does that mean the skill is broken?

Not necessarily. Next check whether you need a full rescan and whether the directory root, copy strategy, or link strategy is correct. Only after that should you suspect SKILL.md itself.

If you think of a refresh button as a tiny cosmetic feature, you underestimate what it does in an execution-oriented product. It does not just add another icon to the UI. It restores clear causal feedback and user control in the discovery layer. That is exactly why a resident assistant like GoWork needs not only a capable model, but also product mechanisms that keep indexing, paths, and execution entry points aligned. For the larger picture, continue with why a newly added skill may stay invisible until cache refresh in GoWork, why multi-step tasks need plans that persist across runs, and the GoWork download page.