# How to Debug Claude Skills Not Activating or Loading Correctly

> Fix Claude Skills activation issues. Learn to debug missing YAML front-matter, plugin registration, and MCP authentication for smooth skill loading. Validate manifests and dependencies now.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Claude Skills are lazy-loaded instruction packages that require valid YAML front-matter in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md), proper plugin registration via `--plugin-dir`, and valid MCP authentication to activate; debugging requires systematically validating the skill manifest, plugin integration, and runtime dependencies layer by layer.**

When working with the **ComposioHQ/awesome-claude-skills** repository, understanding the lazy-loading architecture is essential to debug Claude Skills not activating or loading correctly. Each skill consists of a folder containing a [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file (with YAML front-matter) and optional auxiliary assets. At session start, Claude receives only the skill’s name and description (approximately 100 tokens), while the full body of [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) and extra files fetch on-demand the first time the agent deems the skill relevant.

## Understanding the Lazy-Loading Architecture

According to the repository source code, Claude Skills are implemented as **lazy-loaded instruction packages**. The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file serves as the entry point, containing YAML front-matter defining metadata (name, description) followed by the skill body. When you trigger a skill through its command phrase (e.g., `#webapp-testing`), Claude fetches the complete instruction set rather than preload all skills at startup. This architecture minimizes token usage but introduces specific failure points when manifests are malformed, plugins misconfigured, or authentication tokens expired.

## Six Diagnostic Layers for Skill Activation Failures

### Layer 1: Skill Manifest Validation

Invalid YAML front-matter is the most common cause of silent skill failures. The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file must contain valid `name` and `description` fields in its front-matter, and the total token count must not exceed **5,000 tokens**.

- Open the skill’s [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) (e.g., [`webapp-testing/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/webapp-testing/SKILL.md)) and validate the YAML structure using a tool like `yq` or an online YAML validator.
- Check the file size and token count. Exceeding the 5,000-token limit causes the loader to reject the skill silently.
- Ensure auxiliary files are placed within the skill’s folder; stray scripts in parent directories will not load.

### Layer 2: Plugin Integration

The Claude CLI must recognize the plugin directory through the `--plugin-dir` flag, and the [`plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/plugin.json) manifest must contain required keys.

- Verify you launched Claude with the correct path: `claude --plugin-dir ./connect-apps-plugin`.
- Inspect [`connect-apps-plugin/.claude-plugin/plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/connect-apps-plugin/.claude-plugin/plugin.json) to ensure it contains valid `name`, `description`, and `skills` arrays.
- Run the installation step and watch console output for plugin loading errors.

### Layer 3: MCP Gateway and Authentication

Skills relying on Composio’s MCP (Model Context Protocol) gateway require valid API keys and network connectivity.

- Re-run the `/connect-apps:setup` command and ensure your API key is accepted.
- Test connectivity to the MCP endpoint: `curl https://api.composio.dev/health` should return `{ "status": "ok" }`.
- Check for expired or missing Composio API keys in your environment configuration.

### Layer 4: Runtime Environment Dependencies

Many skills require specific runtime versions or OS-level binaries to execute auxiliary scripts.

- Verify Node.js ≥ 18 or Python ≥ 3.9 is installed for skills with automation scripts.
- Check the skill’s `scripts/` folder for [`requirements.txt`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/requirements.txt) or [`package.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package.json) and install dependencies.
- Install OS-level tools referenced in the skill’s documentation (e.g., `ffmpeg` for video-processing skills).

### Layer 5: Logging and Debug Visibility

When skills fail before reaching the loading stage, standard output may show nothing without verbose logging enabled.

- Launch Claude with debug output: `export CLAUDE_DEBUG=1 && claude --plugin-dir ./connect-apps-plugin`.
- Inspect logs for specific error strings such as *“loading skill …”* or *“failed to parse SKILL.md”*.
- Console output during plugin initialization (lines 50-58 in the source reference) reveals whether the plugin directory was discovered.

### Layer 6: Hidden Edge Cases

Duplicate skill names across folders or special characters in filenames can cause unpredictable loading behavior.

- Search for duplicate `name:` values across the repository: `grep -R "name:" */SKILL.md`.
- Rename files containing Unicode characters to ASCII-only identifiers, as these may break the loader on Windows systems.

## Step-by-Step Debugging Workflow

Follow this sequential workflow to isolate the failure layer:

1. **Confirm plugin installation**: Run `claude --plugin-dir ./connect-apps-plugin` and verify the *“plugin loaded”* message appears in the console output.
2. **Execute setup commands**: Inside Claude, run `/connect-apps:setup` and confirm the API key authentication succeeds.
3. **Trigger the skill**: Use the skill’s trigger phrase (e.g., `#webapp-testing`). If no response occurs, proceed to manifest validation.
4. **Validate the skill manifest**: Check [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) front-matter syntax and token count.
5. **Enable debug logging**: Set `CLAUDE_DEBUG=1` before starting Claude to capture parsing errors.
6. **Test MCP connectivity**: Verify the endpoint health via `curl` to rule out network or authentication issues.
7. **Install runtime dependencies**: Follow the skill’s [`setup.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/setup.md) or README instructions to install missing packages.

## Code Examples for Manual Validation

Use these commands to validate your skill configuration before starting Claude:

```bash

# Start Claude with verbose debug output to catch loading errors

export CLAUDE_DEBUG=1
claude --plugin-dir ./connect-apps-plugin

# Inside Claude, run the setup command to verify authentication

/connect-apps:setup

# Manually test a skill's YAML front-matter using yq

yq eval '.' webapp-testing/SKILL.md | head -n 10

# Check for duplicate skill names that could cause conflicts

grep -R "name:" */SKILL.md | sort | uniq -d

```

```python

# Validate token count of SKILL.md to ensure it stays under 5000 tokens

from transformers import GPT2TokenizerFast

tokenizer = GPT2TokenizerFast.from_pretrained("gpt2")
with open("webapp-testing/SKILL.md", "r") as f:
    tokens = tokenizer.encode(f.read())
    
print(f"Token count: {len(tokens)}")
if len(tokens) > 5000:
    print("ERROR: Skill exceeds 5000 token limit")

```

## Key Source Files for Reference

Understanding these specific files in the **ComposioHQ/awesome-claude-skills** repository accelerates debugging:

- **[`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md)**: Contains the high-level architecture explanation describing lazy-loading behavior and the ≈100 token initial payload.
- **[`connect-apps-plugin/.claude-plugin/plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/connect-apps-plugin/.claude-plugin/plugin.json)**: Defines the plugin discovery metadata required by Claude; missing fields here prevent all contained skills from loading.
- **[`webapp-testing/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/webapp-testing/SKILL.md)**: Example implementation showing proper front-matter structure, description formatting, and optional `scripts/` folder integration.
- **[`connect-apps-plugin/commands/setup.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/connect-apps-plugin/commands/setup.md)**: Provides the authentication flow for MCP gateway connectivity.

## Summary

- Claude Skills use **lazy-loading**, fetching full instructions only when triggered, which requires valid YAML front-matter in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md).
- **Token limits** (5,000 maximum) and invalid front-matter are the primary causes of skills failing to appear.
- Plugin integration requires correct `--plugin-dir` flags and valid [`plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/plugin.json) configuration in the `.claude-plugin` directory.
- **MCP authentication** and runtime dependencies (Node, Python, OS binaries) must be verified when skills load but fail to execute.
- Enable **`CLAUDE_DEBUG=1`** to expose parsing errors and loading stage failures not visible in standard output.

## Frequently Asked Questions

### Why does my skill not appear in the Claude interface even after installing the plugin?

If the skill does not appear, the Claude CLI likely failed to parse the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) manifest. Verify the YAML front-matter contains both `name` and `description` fields, ensure the file is under 5,000 tokens, and launch with `CLAUDE_DEBUG=1` to check for *“failed to parse SKILL.md”* errors in the console output.

### How do I verify that my API key is correctly configured for MCP gateway skills?

Execute the `/connect-apps:setup` command within a Claude session and observe the authentication response. Additionally, run `curl https://api.composio.dev/health` from your terminal; a successful response confirms network connectivity and endpoint availability, while authentication errors indicate an invalid or expired Composio API key.

### What causes the "skill loaded but not executing" behavior?

This typically indicates a **runtime dependency** issue rather than a loading failure. Check the skill’s `scripts/` directory for [`requirements.txt`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/requirements.txt) or [`package.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/package.json) files, verify your Node.js version is ≥ 18 or Python is ≥ 3.9, and ensure OS-level binaries (like `ffmpeg` or `playwright`) are installed and available in your system PATH.

### Can duplicate skill names cause loading conflicts?

Yes. When multiple skills share identical `name` values in their YAML front-matter, the loader may select the wrong skill or fail to register both. Use `grep -R "name:" */SKILL.md` to identify duplicates, and rename skills to ensure unique identifiers across your plugin directory.