Troubleshooting

Installation issues

`ontoskills install mcp` fails

Check:

Node.js 18+ is available
The release artifacts for the current version exist
Your machine can download GitHub release assets
No proxy or firewall is blocking github.com and api.github.com

Error: “Failed to fetch release metadata”

Network connectivity issue. Check your internet connection and try again. If behind a corporate proxy:

export HTTPS_PROXY=http://proxy.example.com:8080
ontoskills install mcp

Error: “Release does not contain asset”

The platform may not be supported. Check available platforms:

# Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64
uname -m && uname -s

`ontoskills install core` fails

The compiler requires Python 3.10+:

python3 --version

If Python is installed but not found:

export PYTHON=/path/to/python3
ontoskills install core

Store and package issues

”Package not found”

Check the package ID spelling
Run ontoskills search <query> to discover available packages
If using a third-party store, verify it’s configured:

ontoskills store list

Store skill does not appear in OntoMCP

Skills are enabled by default on install. If a skill is not visible:

Check if it was disabled:

ontoskills list-installed

Re-enable if needed:

ontoskills enable mareasw/greeting/hello

Rebuild the index:

ontoskills rebuild-index

Restart the MCP process

”Skill still not visible after enable”

The MCP server caches the ontology index. Ensure:

Index was rebuilt: ontoskills rebuild-index
MCP server was restarted (close and reopen your AI client)
Check ~/.ontoskills/ontologies/system/index.enabled.ttl exists

Compiler issues

Compiler commands fail

Install the compiler first:

ontoskills install core

Then initialize the ontology foundation:

ontoskills init-core

“ANTHROPIC_API_KEY not set”

The compiler requires an Anthropic API key for LLM-based knowledge extraction:

export ANTHROPIC_API_KEY="your-key-here"
ontoskills compile my-skill

Add to your shell profile (~/.bashrc, ~/.zshrc) to persist.

”SHACL validation failed”

Your skill is missing required fields. Check:

At least one resolvesIntent (in “When To Use” section)
A clear one-line nature statement at the top
Proper YAML frontmatter with name and description

Run with verbose output for details:

ontoskills compile my-skill -v

“Nature not extracted”

Add a clear one-line summary at the beginning of your SKILL.md:

# Skill Title

A brief description of what this skill does.

## What It Does
...

“Missing resolvesIntent”

Ensure your skill has a “When To Use” or similar section:

## When To Use

Use this skill when the user wants to extract text from PDF files.

Import issues

Imported source repo compiled, but the skill still is not visible

Imported skills are enabled by default. If not visible:

Rebuild the index:

ontoskills rebuild-index

Restart the MCP process
If still not visible and the skill was previously disabled, re-enable it:

ontoskills enable <qualified-id>
ontoskills rebuild-index

“Source import failed”

Ensure:

Git is installed and accessible
The repository URL is correct and accessible
OntoCore is installed: ontoskills install core

”No SKILL.md files found”

The import process looks for SKILL.md files in the repository. Ensure:

Files are named exactly SKILL.md (case-sensitive)
Files are in the repository root or subdirectories
Files have valid YAML frontmatter

MCP connection issues

”MCP server not starting”

Check the binary exists and is executable:

ls -la ~/.ontoskills/bin/ontomcp

If missing, reinstall:

ontoskills install mcp

“Connection refused” or “Timeout”

The MCP server may be slow to start. Check:

Server is running: ps aux | grep ontomcp
No port conflicts
Sufficient system resources

”Claude Code cannot find ontomcp”

Ensure ~/.ontoskills/bin is in your PATH, or use the full path in your MCP configuration:

{
  "command": "/home/user/.ontoskills/bin/ontomcp"
}

Index and state issues

”Index corrupted”

Rebuild from scratch:

ontoskills rebuild-index

If that fails, check the lock file:

cat ~/.ontoskills/state/registry.lock.json

“State files missing”

The state directory should contain:

registry.sources.json — configured stores
registry.lock.json — installed packages

If missing, they’ll be recreated on next operation.

”Permission denied” errors

Check ownership of ~/.ontoskills/:

ls -la ~/.ontoskills/

Fix permissions if needed:

chmod -R u+rw ~/.ontoskills/

Diagnostic tools

`ontoskills doctor`

Run a comprehensive health check:

ontoskills doctor

This checks:

MCP binary exists and is executable
Core ontology is valid
Environment variables are set
Index is consistent
Available updates

Verbose output

Most commands support -v for detailed logging:

ontoskills compile my-skill -v
ontoskills install mcp -v

Reset and recovery

Reset everything

To remove the entire managed home:

ontoskills uninstall --all

Warning: This deletes everything under ~/.ontoskills/.

Reinstall from scratch

ontoskills uninstall --all
ontoskills install mcp
ontoskills install core  # if needed
ontoskills init-core     # if needed
# Re-install skills
ontoskills install mareasw/greeting/hello

Getting help

If your issue isn’t covered here:

Run ontoskills doctor and check the output
Search existing issues on GitHub
Open a new issue with:
- ontoskills doctor output
- Command that failed
- Error message
- Your OS and version