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

> Discover how the agent-skills cache mechanism works and manage it manually using CLI commands or the API. Learn about content hash validation for efficient skill caching.

- Repository: [TechLeads.club 💎/agent-skills](https://github.com/tech-leads-club/agent-skills)
- Tags: internals
- Published: 2026-05-18

---

**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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) within the skill folder to confirm a cache hit.
3. **Validation**: If [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) exists, `readCachedSkillMeta()` compares the stored `contentHash` in [`.skill-meta.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.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`](https://github.com/tech-leads-club/agent-skills/blob/main/skills-registry.json)) respects a hard TTL of **24 hours** defined by `REGISTRY_CACHE_TTL_MS` in [`constants.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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:

```bash
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`](https://github.com/tech-leads-club/agent-skills/blob/main/skills-registry.json) | `clearRegistryCache(ports)` |

### Force-Reinstalling a Skill

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

```bash
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`:

```typescript
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:

```bash

# 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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/skills-registry.json) matches your local [`.skill-meta.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.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.