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

Enable verbose logging with SKILL_DEBUG=1, inspect the lockfile at .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 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, 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 and 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, validated using Zod schemas in 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 file with valid YAML front-matter including name, description, category, and version fields.

The validator in 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 logic.

Agent Configuration Mismatches

The 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 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 (engines field) and enforced by 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:

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

The 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:

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:

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

ls -l ~/.cache/agent-skills

If missing, create it with proper permissions:

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

5. Verify skill integrity

Open the problematic 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 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:

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

Failing tests in 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 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

"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 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 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 remains enabled (default behavior).

Code Examples for Deep Debugging

Enable debug logging for a single command:

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

Manually clear cache and lockfile before reinstalling:

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:

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:

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
• Check .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
• Validate SKILL.md files against the JSON schema in tools/skill-plugin/src/generators/skill/schema.json
• Confirm agent compatibility in 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

Frequently Asked Questions

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

This error indicates that .agents/.skill-lock.json contains invalid JSON or fails Zod schema validation defined in 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. 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 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 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 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 if you need to override default agent detection.

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