Skill Cache Mechanism in Agent-Skills: How It Works and How to Manage It Manually

The Agent-Skills CLI stores downloaded skills in ~/.cache/agent-skills, validates cache freshness via content hashes rather than timestamps, and exposes manual management through the agent-skills cache command and a programmatic core API.

The skill cache mechanism in the Agent-Skills repository eliminates redundant network requests by persisting skill files locally and verifying them against cryptographic hashes. By default, the cache resides in ~/.cache/agent-skills (or $XDG_CACHE_HOME/agent-skills) and maintains both a mirrored skills registry and individual skill directories containing metadata. Understanding this caching layer allows you to troubleshoot stale content, force refreshes, and reclaim disk space without relying on hidden implementation details.

How the Skill Cache Mechanism Works

The cache operates as a two-tier system: a registry index and per-skill file storage. When you request a skill, the core service resolves the cache location, validates existing content, and conditionally fetches updates only when hashes mismatch.

Cache Directory Structure

The filesystem layout follows a predictable hierarchy defined in libs/core/src/lib/constants.ts:

~/.cache/agent-skills/
├── skills-registry.json      # Cached copy of remote registry (24h TTL)

└── skills/
    └── <skill-name>/
        ├── SKILL.md          # Primary skill definition

        ├── ...               # Supporting scripts/templates

        └── .skill-meta.json  # Content hash and download timestamp

The base directory is computed by combining CACHE_BASE_DIR (defined as '.cache') with the user's home directory and a namespace constant to form the full path.

Cache Resolution Logic

In libs/core/src/lib/services/registry.service.ts, the resolution flow follows three distinct steps:

1. Path Resolution: getSkillCachePath() (lines 50–55) sanitizes the skill name using sanitizeName() and returns <cache-dir>/skills/<safe-name>.
2. Hit Detection: isSkillCachedInternal() (lines 34–39) checks for the existence of SKILL.md within the skill folder to confirm a cache hit.
3. Validation: If SKILL.md exists, readCachedSkillMeta() compares the stored contentHash in .skill-meta.json against the remote registry hash. Mismatches trigger ensureSkillDownloaded() (lines 434–452) to fetch fresh files.

TTL and Refresh Policies

The registry cache (skills-registry.json) respects a hard TTL of 24 hours defined by REGISTRY_CACHE_TTL_MS in constants.ts. Individual skill files have no expiration timestamp; they persist indefinitely until their content hash changes or you manually force a refresh.

Manual Cache Management via CLI

The CLI wrapper in packages/cli/src/cli/cache.ts exposes granular cache control through subcommands and flags.

Inspecting the Cache Location

To verify where skills are stored on your machine:

agent-skills cache --path

This outputs the absolute path (e.g., /home/user/.cache/agent-skills) resolved by getCacheDir().

Clearing Cache Data

Command	Function	API Equivalent
agent-skills cache --clear	Deletes the entire <cache-dir> including skills and registry	clearCache(ports)
agent-skills cache --clear-registry	Removes only skills-registry.json	clearRegistryCache(ports)

Force-Reinstalling a Skill

To bypass the cache for a specific skill, use the --force flag during installation:

agent-skills install accessibility --force

This invokes forceDownloadSkill() (lines 515–527), which removes the skill's cache folder recursively before re-downloading.

Programmatic Cache Control with the Core API

For automation scripts or IDE integrations, import cache utilities directly from @tech-leads-club/core:

import {
  getSkillCachePath,
  clearCache,
  clearRegistryCache,
  getCacheDir,
  forceDownloadSkill,
} from '@tech-leads-club/core';

// Resolve cache locations
const cacheRoot = getCacheDir(ports);
const skillPath = getSkillCachePath(ports, 'accessibility');

// Cleanup operations
clearCache(ports);           // Wipe everything
clearRegistryCache(ports);   // Wipe only registry index

// Force refresh single skill
await forceDownloadSkill(ports, 'accessibility');

Note that ports represents the platform-agnostic service collection (filesystem, HTTP, environment) defined in libs/core/src/lib/ports/*.ts.

Direct Filesystem Operations

You can manipulate the cache directly via shell commands when the CLI is unavailable:

# List cached skills

ls ~/.cache/agent-skills/skills

# Remove specific skill

rm -rf ~/.cache/agent-skills/skills/accessibility

# Clear registry only

rm ~/.cache/agent-skills/skills-registry.json

Safety Consideration: The library validates write paths using isPathSafe() (lines 8–12 in registry.service.ts) to prevent path-traversal attacks. When deleting files manually, ensure you remain within the cache directory boundary.

Summary

• Location: Cache defaults to ~/.cache/agent-skills, composed from CACHE_BASE_DIR and user home.
• Detection: A skill is considered cached when SKILL.md exists in its directory (isSkillCachedInternal).
• Freshness: Skills update only when content hashes mismatch; the registry refreshes every 24 hours (REGISTRY_CACHE_TTL_MS).
• Cleanup: Use agent-skills cache --clear for total reset, --clear-registry for index-only refresh, or forceDownloadSkill() for per-skill updates.
• Safety: All paths are sanitized via sanitizeName() and validated through isPathSafe() to prevent directory traversal.

Frequently Asked Questions

Where is the Agent-Skills cache stored?

By default, the cache resides in ~/.cache/agent-skills on Linux/macOS or the equivalent path derived from $XDG_CACHE_HOME. The exact location is computed at runtime by combining the user’s home directory with CACHE_BASE_DIR (defined in libs/core/src/lib/constants.ts line 44) and the namespace constant.

How do I force a skill to re-download?

Use the --force flag with the install command (agent-skills install <skill> --force) or call forceDownloadSkill(ports, 'skill-name') programmatically. Both methods delete the existing skill cache folder before fetching fresh files from the remote registry.

Why is my skill not updating despite registry changes?

The cache validates skills by content hash, not filename. If the remote skill’s hash in skills-registry.json matches your local .skill-meta.json, the cached version is served. Clear the specific skill folder or run agent-skills cache --clear-registry to fetch the latest registry index and trigger hash comparisons.

Is it safe to delete cache files manually?

Yes, provided you stay within the ~/.cache/agent-skills directory. The library uses isPathSafe() to validate paths during writes, but manual deletion requires user discretion. Avoid deleting parent directories or files outside the cache root, as this will not affect the CLI’s operation but may remove unrelated data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}