# How to Debug Skill Installation Failures and Common CLI Issues in Agent Skills

> Troubleshoot Agent Skills CLI installation failures. Learn to debug errors by enabling verbose logging, checking the lockfile, and verifying cache write permissions.

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

---

**Enable verbose logging with `SKILL_DEBUG=1`, inspect the lockfile at [`.agents/.skill-lock.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.agents/.skill-lock.json), and verify write permissions to `~/.cache/agent-skills` to resolve most Agent Skills CLI installation failures.**

The Agent Skills CLI manages markdown-based instruction packages (skills) for AI coding agents like Cursor and Claude Code. When `agent-skills install` fails, the root cause typically stems from network connectivity issues, cache permission errors, lockfile corruption, or invalid skill definitions according to the `@tech-leads-club/agent-skills` source code.

## Common Root Causes of Installation Failures

### Network and Registry Fetch Failures

The CLI fetches [`skills-registry.json`](https://github.com/tech-leads-club/agent-skills/blob/main/skills-registry.json) from a CDN to resolve skill locations. Failures manifest as "Failed to download registry" or "Unable to fetch skill files".

According to [`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 service retrieves the registry from `https://cdn.jsdelivr.net/npm/agent-skills@latest/skills-registry.json`. Check your internet connectivity, proxy settings, and verify the JSON is well-formed and contains valid `sha256` entries for integrity checks.

### Cache Directory Permission Issues

The installer writes skill files to a platform-specific cache directory. On Linux/macOS, this defaults to `~/.cache/agent-skills`; on Windows, it falls back to `%LOCALAPPDATA%`.

As implemented in [`libs/core/src/lib/services/global-path.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/global-path.service.ts) and [`libs/core/src/lib/services/installer.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/installer.service.ts), "Permission denied" errors indicate the CLI cannot write to these paths. Ensure the directory exists and is writable, or check Windows-specific fallback behavior in the global path resolver.

### Lockfile Corruption and Validation

The CLI maintains installation state in [`.agents/.skill-lock.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.agents/.skill-lock.json), validated using Zod schemas in [`libs/core/src/lib/services/lockfile.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/lockfile.service.ts).

Errors like "Lockfile validation failed" or "Lockfile is out of sync" indicate corrupted JSON or schema mismatches. Delete the lockfile and reinstall, or use `agent-skills lockfile repair` if provided by your CLI version.

### Skill Definition Schema Violations

Each skill requires a [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) file with valid YAML front-matter including `name`, `description`, `category`, and `version` fields.

The validator in [`tools/skill-plugin/src/generators/skill/schema.json`](https://github.com/tech-leads-club/agent-skills/blob/main/tools/skill-plugin/src/generators/skill/schema.json) rejects skills missing required sections like `Use when` and `Do NOT use for`. Open the offending file path shown in the CLI error and check for YAML syntax errors or prohibited HTML tags (`<`/`>` characters) that break the [`markdown-parser.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/markdown-parser.service.ts) logic.

### Agent Configuration Mismatches

The [`agents.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/agents.service.ts) file defines supported agents and their skill directories. "No matching agent found" or "Unsupported agent tier" errors occur when you pass an unsupported agent name (e.g., `cursor`, `claude-code`).

Verify the agent exists in [`libs/core/src/lib/services/agents.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/agents.service.ts) and that its `skillsDir` and `globalSkillsDir` resolve correctly for your operating system.

### Version Compatibility Errors

The CLI requires Node.js ≥ 22 as specified in [`packages/cli/package.json`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/package.json) (engines field) and enforced by [`packages/cli/src/services/package-info.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/src/services/package-info.ts). 

Run `node -v` to verify your runtime meets the minimum version, and check `npm view @tech-leads-club/agent-skills version` to ensure CLI compatibility.

## Step-by-Step Debugging Workflow

1. **Enable verbose logging**

Re-run the failing command with the debug flag:

```bash
SKILL_DEBUG=1 agent-skills install <skill-name>

```

The [`installer.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/installer.service.ts) checks `process.env.SKILL_DEBUG` and prints detailed steps including registry fetch URLs, cache paths, and lockfile write operations.

2. **Inspect the lockfile**

Examine the atomic lockfile created by [`lockfile.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/lockfile.service.ts):

```bash
cat .agents/.skill-lock.json | jq .

```

Look for malformed JSON, missing hash entries, or version mismatches that trigger validation failures.

3. **Validate the registry JSON**

Manually fetch the registry to verify CDN availability and data integrity:

```bash
curl -s https://cdn.jsdelivr.net/npm/agent-skills@latest/skills-registry.json | jq .

```

Missing `sha256` fields in the registry cause integrity check failures during the installation phase.

4. **Check cache directory permissions**

```bash
ls -l ~/.cache/agent-skills

```

If missing, create it with proper permissions:

```bash
mkdir -p ~/.cache/agent-skills && chmod 700 ~/.cache/agent-skills

```

5. **Verify skill integrity**

Open the problematic [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) (the error message provides the absolute path) and confirm:
- Valid YAML front-matter parsable by the internal markdown parser
- No prohibited HTML tags
- Presence of required `Use when` and `Do NOT use for` sections

6. **Check agent configuration**

Review [`libs/core/src/lib/services/agents.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/agents.service.ts) to confirm your target agent's configuration matches the local environment, particularly the `skillsDir` resolution for your OS.

7. **Run unit tests**

Execute the test suite to identify regressions in the installation pipeline:

```bash
npm run test --workspace=@tech-leads-club/agent-skills

```

Failing tests in [`installer.service.spec.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/installer.service.spec.ts) often indicate breaking changes in the installation logic.

8. **Consult UI error handling**

For interactive installation issues, examine [`packages/cli/src/views/InstallWizard.tsx`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/src/views/InstallWizard.tsx) to understand how the TUI surfaces errors to the user, which helps reproduce issues in the React-based interface.

## Resolving Common CLI Errors

**"Failed to fetch registry"**
- Verify network proxy settings
- Retry the operation later if the CDN returns 503
- Run `agent-skills cache clear` to force a fresh registry fetch via [`packages/cli/src/services/update-cache.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/src/services/update-cache.ts)

**"Permission denied writing lockfile"**
- Run the CLI with appropriate user privileges
- Adjust file permissions: `chmod 600 .agents/.skill-lock.json`
- Check that the `.agents` directory is owned by the current user

**"Skill not found"**
- Ensure the skill name matches exactly the `name` field in its [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) front-matter
- Run `agent-skills list` to view available skills in the current registry

**"Invalid front-matter"**
- Fix YAML indentation or stray characters in the [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) file
- Run `npm run lint` to validate skill definitions against the schema

**"Symlink creation failed"**
On Windows, the installer falls back to copy mode when symlinks are unavailable. Ensure the `copyOnWindows` flag in [`libs/core/src/lib/services/installer.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/installer.service.ts) remains enabled (default behavior).

## Code Examples for Deep Debugging

Enable debug logging for a single command:

```bash
SKILL_DEBUG=1 agent-skills install git-history-viewer

```

Manually clear cache and lockfile before reinstalling:

```bash
rm -rf ~/.cache/agent-skills
rm -f .agents/.skill-lock.json
agent-skills install git-history-viewer

```

Programmatically verify skill integrity using the core library:

```typescript
import { readFile } from 'fs/promises';
import { createHash } from 'crypto';
import { RegistryService } from '@tech-leads-club/core';

async function verifySkill(skillName: string) {
  const reg = await RegistryService.load();
  const skill = reg.skills.find(s => s.name === skillName);
  if (!skill) throw new Error('Skill not found in registry');

  const file = await readFile(
    `${process.env.HOME}/.cache/agent-skills/${skill.path}`,
  );
  const hash = createHash('sha256').update(file).digest('hex');
  console.log('Expected:', skill.sha256);
  console.log('Actual  :', hash);
  console.log(hash === skill.sha256 ? '✅ OK' : '❌ MISMATCH');
}

verifySkill('git-history-viewer');

```

Access lockfile data programmatically:

```typescript
import { LockfileService } from '@tech-leads-club/core';

async function dumpLockfile() {
  const lock = await LockfileService.load();
  console.table(lock.installedSkills);
}

dumpLockfile();

```

## Summary

- Set `SKILL_DEBUG=1` to reveal detailed installation steps in [`installer.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/installer.service.ts)
- Check [`.agents/.skill-lock.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.agents/.skill-lock.json) for corruption and delete it to force reinstallation
- Verify write access to `~/.cache/agent-skills` (or `%LOCALAPPDATA%` on Windows) via [`global-path.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/global-path.service.ts)
- Validate [`SKILL.md`](https://github.com/tech-leads-club/agent-skills/blob/main/SKILL.md) files against the JSON schema in [`tools/skill-plugin/src/generators/skill/schema.json`](https://github.com/tech-leads-club/agent-skills/blob/main/tools/skill-plugin/src/generators/skill/schema.json)
- Confirm agent compatibility in [`libs/core/src/lib/services/agents.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/agents.service.ts)
- Use `curl` to test CDN connectivity for the registry JSON
- Ensure Node.js ≥ 22 compatibility as specified in [`packages/cli/package.json`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/package.json)

## Frequently Asked Questions

### What does "Lockfile validation failed" mean and how do I fix it?

This error indicates that [`.agents/.skill-lock.json`](https://github.com/tech-leads-club/agent-skills/blob/main/.agents/.skill-lock.json) contains invalid JSON or fails Zod schema validation defined in [`libs/core/src/lib/services/lockfile.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/lockfile.service.ts). Delete the lockfile and run the install command again, or use `agent-skills lockfile repair` if your CLI version supports it. The lockfile is created atomically, but interrupting the process can leave it in an invalid state.

### Why do I get "Permission denied" errors on Windows?

The CLI attempts to write to `%LOCALAPPDATA%` when `~/.cache` is unavailable according to [`global-path.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/global-path.service.ts). Ensure your user has write permissions to the fallback directory, or run the terminal as Administrator if the installer cannot create symlinks (though [`installer.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/installer.service.ts) defaults to `copyOnWindows` for compatibility).

### How can I verify a skill downloaded correctly?

Compare the SHA-256 hash of the cached file against the registry entry. The `RegistryService` 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) loads the cached registry JSON containing expected hashes. Use the Node.js `crypto` module to generate the actual hash of the file in `~/.cache/agent-skills/` and compare values.

### What should I check when the CLI reports "No matching agent found"?

Open [`libs/core/src/lib/services/agents.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/agents.service.ts) to view the list of supported agents (e.g., `cursor`, `claude-code`). Ensure you pass the exact agent identifier as defined in this file, and verify that the agent's `skillsDir` resolves correctly for your operating system. Check [`packages/cli/src/services/config.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/src/services/config.ts) if you need to override default agent detection.