# How to Troubleshoot Skill Loading Issues in Anthropic Plugins: A Complete Guide > Troubleshoot skill loading issues in Anthropic plugins. This guide covers verifying SKILL.md files, removing placeholders, and repackaging with package_data_skill.py for correct .skill zip paths. - Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) - Tags: how-to-guide - Published: 2026-05-25 --- **Troubleshoot skill loading issues in Anthropic plugins by verifying that each skill folder contains a valid [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file with proper YAML front-matter, removing placeholder text, and repackaging using the [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) validator to ensure the `.skill` zip maintains correct relative paths.** When building extensions for Claude using the `anthropics/knowledge-work-plugins` repository, skill loading failures can halt development. These errors typically stem from malformed skill manifests, missing metadata, or incorrect packaging of the `.skill` archive. Understanding the validation pipeline and using the built-in troubleshooting tools will help you resolve these issues quickly. ## Understanding the Skill Loading Pipeline Claude loads skills through a four-stage process defined in the plugin architecture: - **Manifest Discovery**: Claude reads [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) to locate the `skills/` directory. - **Skill Scanning**: Each subfolder is scanned for a required [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file containing YAML front-matter with `name`, `description`, and `version` fields. - **Validation**: The helper script [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) checks for file presence, validates front-matter syntax, and ensures no placeholder text remains. - **Packaging**: Skills are compressed into `.skill` zip files that must preserve the original folder structure for asset path resolution. ## Common Skill Loading Errors and Solutions ### Missing or Misnamed SKILL.md **Symptom**: "Skill could not be loaded" or "Missing SKILL.md". **Fix**: Ensure a file named exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) exists at the root of the skill folder. The validator in [`data/skills/data-context-extractor/scripts/package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/data-context-extractor/scripts/package_data_skill.py) explicitly checks for this file before proceeding. ### Invalid YAML Front-Matter **Symptom**: "SKILL.md missing YAML frontmatter" or validation failures. **Fix**: The front-matter must appear at the very top of the file with no leading whitespace or comments: ```markdown --- name: Data Context Extractor description: Extracts contextual metadata from tabular data. version: 1.0.0 --- ``` ### Placeholder Text Detection **Symptom**: Validation errors mentioning "TODO" or placeholder content. **Fix**: Remove all boilerplate strings like "TODO: replace..." before packaging. The `validate_skill` function scans for leftover template text that indicates incomplete development. ### Incorrect Zip Layout **Symptom**: Asset path resolution failures or "File not found" errors at runtime. **Fix**: The `.skill` archive must contain files relative to the skill folder root, not nested in an extra directory. The packaging script uses `zipfile.ZipFile` with `ZIP_DEFLATED` compression to ensure proper structure. ## Step-by-Step Troubleshooting Workflow 1. **Locate the skill folder** ```bash $ tree my-plugin/skills/ ``` 2. **Run the validator** ```bash $ python data/skills/data-context-extractor/scripts/package_data_skill.py /path/to/skill-folder/ ``` This executes the same validation logic as the Claude runtime, returning specific errors like `Missing SKILL.md` or `Invalid front-matter`. 3. **Inspect SKILL.md syntax** Verify the YAML block is exactly at the top with three dashes: ```markdown --- name: My Skill description: Skill description here. version: 1.0.0 --- ``` 4. **Re-package the skill** ```bash $ python data/skills/data-context-extractor/scripts/package_data_skill.py /path/to/skill-folder/ ``` This creates `skill-name.zip` in the current directory while maintaining the correct relative paths required by the runtime. 5. **Update plugin manifest** Ensure [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) references the correct generated zip file. 6. **Reload and verify** Restart the Claude session to confirm the skill loads without errors. ## Programmatic Validation and Packaging Validate skills directly in Python using the same function called by the CLI: ```python from pathlib import Path from data.skills.data_context_extractor.scripts.package_data_skill import validate_skill skill_path = Path("/path/to/skill-folder") valid, msg = validate_skill(skill_path) print("✅ Skill OK" if valid else f"❌ {msg}") ``` Package for distribution with explicit output directory: ```bash $ python data/skills/data-context-extractor/scripts/package_data_skill.py \ /path/to/skill-folder \ /tmp/output ``` The script outputs the path to the generated `.skill` file, confirming successful packaging. ## Summary - **Skill loading requires** a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file with valid YAML front-matter (`name`, `description`, `version`) at the folder root. - **Validate locally** using [`data/skills/data-context-extractor/scripts/package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/data-context-extractor/scripts/package_data_skill.py) to catch errors before deployment. - **Remove placeholders** and ensure no "TODO" text remains in the final skill files. - **Package correctly** using the provided script to maintain proper zip structure and relative asset paths. - **Sync the manifest** in [`.claude-plugin/plugin.json`](https://github.com/anthropics/knowledge-work-plugins/blob/main/.claude-plugin/plugin.json) with the generated `.skill` file name. ## Frequently Asked Questions ### Why does Claude report "Missing SKILL.md" when the file exists? The file must be named exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) (case-sensitive) and located at the root of the skill folder, not in subdirectories. The validator in [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) checks for this specific path. Additionally, ensure the file has proper read permissions for the runtime user and that paths do not exceed 255 characters. ### What fields are required in the SKILL.md front-matter? The YAML block must include three mandatory fields: `name` (the skill identifier), `description` (human-readable summary), and `version` (semantic version string). The front-matter must start at line 1 with no preceding whitespace or comments, delimited by `---` markers. ### How do I fix "Placeholder text detected" errors? Search your [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) for template strings like "TODO:" or "replace this" and remove them. The `validate_skill` function explicitly scans for these patterns to ensure developers don't ship unfinished templates. Replace all boilerplate with final content before running the packager. ### Can I manually zip the skill folder instead of using the script? While possible, manual zipping often creates an extra top-level directory that breaks asset path resolution. The [`package_data_skill.py`](https://github.com/anthropics/knowledge-work-plugins/blob/main/package_data_skill.py) script uses `zipfile.ZipFile` with relative path handling to ensure the archive structure matches what Claude expects. Always use the script to avoid layout errors.