Why a newly added skill may stay invisible until cache refresh in GoWork

If you just added a new skill and GoWork still does not show it, the short answer is this: most of the time, the skill is fine and the discovery index is stale. The loader is still looking at a cached snapshot from an earlier scan. Once the cache TTL expires, you trigger a manual refresh, or a full rescan runs, the skill often appears without any change to the skill itself. The other common cause is path semantics. Older GoWork loaders did not follow junctions or symlinks reliably, so a skill could exist behind a linked directory while the scanner never actually walked into the real folder.

That is why this problem is often misdiagnosed as “installation failed” when it is really “discovery has not caught up yet.” An execution-oriented assistant should know the difference. It should inspect cache state first, directory traversal second, and the skill file itself only after those are ruled out.

This is also consistent with the way the content-pipeline skill documents shared state. Its README explicitly says that topics.md and content-log.md must always be read from D:/omnigoai/.claude/skills/content-pipeline/, even if another agent reads the instructions from a copied directory. In other words, instruction copies may multiply, but the authoritative path must remain singular. Skill discovery follows the same rule. The entry path, the real directory, and the cached index all have to agree.

If you have already read GoWork Assistant: a local AI that actually gets work done, Why multi-step tasks need plans that persist across runs, and Resume AI tasks after failure instead of restarting, this article answers a narrower but very practical question: why can a newly installed skill remain temporarily invisible in GoWork?

The first explanation is also the most common one: skill discovery is not a full disk scan on every UI open

Most desktop systems do not rescan every skill directory every time the panel redraws. They cache discovery results such as which skills were found and what metadata they exposed. GoWork has the same incentive: scanning many folders, parsing metadata, and rebuilding lists on every view would slow the interface down.

So when you add a new skill, the normal flow is closer to this:

read the current discovery cache;
reuse it while its TTL is still valid;
rescan when the TTL expires or the user explicitly requests refresh;
run a broader rescan only when the system needs to rebuild the discovery surface from scratch.

That leads to a perfectly normal but confusing state: the files already exist on disk, but the UI still reflects the previous scan snapshot. The files are real. The index is old.

Why cache TTL is not laziness but part of a stable skill system

It is tempting to think that discovery cache is just avoidable complexity. Why not scan live every time?

Because skill discovery is not a single file read. It may involve:

traversing one or more skill roots;
reading SKILL.md or equivalent metadata from each candidate;
parsing names, descriptions, and applicability;
handling duplicates, damaged folders, and unreadable entries;
rebuilding the UI-facing skill list.

Doing all of that on every panel open often makes the system feel slower and more fragile, not more real-time. TTL is the compromise between freshness and responsiveness.

So cache TTL should not be understood as a bug. It is a rate limiter for discovery work. The real UX question is whether the user has a clear way to invalidate stale cache when they know they have changed the filesystem.

Why waiting for TTL expiry is not the same thing as pressing refresh

These actions may produce the same visible result, but they mean different things.

Waiting for TTL expiry is passive. The system decides the old index has aged out.
Manual refresh is active. The user says: “I changed something. Rebuild the index now.”
Full rescan is heavier. It is useful when the root path changed, the mount strategy changed, or you suspect the previous scan scope itself was incomplete.

These solve different classes of problems. A normal newly added skill often appears after refresh. But if the issue is directory traversal rather than stale cache, waiting may never help because the scanner never reached the real folder in the first place.

One real-world pitfall: older GoWork loaders did not follow junctions or symlinks reliably

This is one of the easiest ways to draw the wrong conclusion.

The content-pipeline cross-agent README contains a very important sentence: some agents’ skill loaders do not follow junctions or symlinks, such as GoWork ≤1.3.x, and this has been fixed in source for a later release. That line matters because it tells you two things:

the skill itself may be completely valid;
the failure may live entirely in discovery traversal semantics.

So if you exposed a skill directory via junction or symlink, an older loader might see the entry path but never walk into the target directory. From the user’s perspective this is maddening:

the directory is visible in the file manager;
the path is accessible from the shell;
but the GoWork skill list still does not contain it.

In that case, repeated refresh will not help because refresh only rebuilds the index from the scanner’s reachable surface. If the scanner cannot follow that surface, the skill never enters cache at all.

Why copying a skill directory can be more reliable than elegant linking

In theory, linked directories are cleaner. One source tree, multiple consumers, no duplication.

But elegance only helps if the consumer actually supports the directory semantics you chose. If the loader does not follow links correctly, insisting on links does not make the system cleaner. It just makes the skill invisible.

That is why the content-pipeline README gives a practical fallback: if an agent does not follow junctions or symlinks, copy the directory into its skill root instead.

That advice is not claiming copies are architecturally superior. It is acknowledging that under the current implementation boundary, copies are easier for the scanner to discover and index correctly.

A better troubleshooting order: inspect the discovery chain before rewriting the skill

When a skill does not show up, the most wasteful move is to immediately rewrite SKILL.md. A better order is this.

1. Confirm that the files are in a directory the current GoWork build actually scans

Not the directory you assume it scans. The directory it really scans. If links are involved, confirm the loader version supports them.

2. Ask whether the cache may still be valid

If the path is correct and the change is recent, try refresh or wait for the TTL boundary before declaring load failure.

3. Trigger a full rescan when the root or mount strategy changed

If you moved the skill root, switched from a copy to a junction, or changed how directories are exposed, a normal refresh may not be enough.

4. Only then inspect the skill file itself

For example, check whether SKILL.md is malformed or the metadata is incomplete. But leave this for last.

The key principle is simple: first verify the discovery path, then verify the skill content. “Not visible” and “not parseable” are different failure classes.

Why absolute paths and shared state matter here too

Skill discovery is not only about whether a card appears in a list. It also affects whether execution later reads the right state.

The content-pipeline docs insist that topics.md and content-log.md always resolve to the shared state under D:/omnigoai/.claude/skills/content-pipeline/, not to whichever copied directory happened to provide the instructions. The reason is straightforward: instruction replicas may exist, but state truth must stay singular.

The same logic applies to skill discovery. If a skill can be surfaced from multiple copies or from stale cached metadata pointing at the wrong source, two subtler problems appear:

you think you updated the skill, but the UI still points at an older copy;
you think the system “forgot” state, but it is actually reading a different file tree.

So “refresh the skill list” is not a cosmetic UI action. It is part of keeping the execution entry point consistent.

Why a refresh button matters

Cache TTL solves performance. A refresh button solves control.

Without an explicit refresh action, users are left guessing:

is the UI still within the cache window?
did the system notice my filesystem change?
should I restart the app?
or should I just wait?

A refresh button reduces that uncertainty to a clear operation: I changed the skill directory, so rebuild the discovery index now.

Its value is not that it adds magical new capability. Its value is that it turns passive waiting into an intentional request for re-indexing.

Why the best design usually combines TTL, refresh, and full rescan

These three mechanisms solve different layers of the same problem:

TTL keeps normal browsing fast and stable;
refresh handles immediate post-change feedback;
full rescan repairs discovery after root-level or traversal-level changes.

If any layer is missing, the experience degrades:

TTL without refresh forces users to wait blindly;
refresh without TTL makes every skill view heavier than necessary;
no full rescan means some discovery problems 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.

FAQ

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

Do not rewrite the skill yet. First confirm that it is inside a directory the current GoWork build actually scans, then try a manual refresh. If you used a junction or symlink, verify that the loader version follows it.

FAQ 2: What is the practical difference between waiting and refreshing?

Waiting depends on cache expiry. Refresh actively invalidates the old index and requests a new scan immediately.

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

Because “the file exists” only proves the filesystem contains it. It does not prove the discovery scanner has traversed and indexed it. The usual reasons are stale cache or unsupported junction/symlink traversal.

FAQ 4: Why can copying the skill directory be more reliable than linking it?

Because when a loader does not follow mapped directories correctly, a real copied folder is easier for the scanner to enter and index. It is less elegant, but more dependable under that implementation constraint.

If your new skill exists on disk but remains invisible for a while, do not assume the skill itself is broken. In many cases, the real question is simpler: is the discovery cache still valid, has refresh actually happened, and did the scanner truly reach the target directory? Once you treat the skill system as an indexed execution surface with path semantics and consistency requirements, this behavior stops looking mysterious. To see how GoWork connects discovery, long-running execution, and persistent task state, continue with GoWork Assistant: a local AI that actually gets work done, why multi-step tasks need persistent plans, and the GoWork download page.