FAQ

This section collects common questions, troubleshooting solutions, and design philosophy explanations encountered during OpenSkills usage, helping you quickly locate and resolve issues.

This Section

FAQ

Answers to common questions about installation, configuration, and usage. Including the differences between OpenSkills and Claude Code, skill installation locations, AGENTS.md sync issues, sharing skills across multiple projects, etc.

Troubleshooting

Provides diagnosis and repair methods for common errors. Covers detailed solution steps for Git clone failures, SKILL.md not found, skills not found, permission errors, update skipping, and other issues.

Why CLI?

Explains OpenSkills' design rationale for choosing CLI over MCP. Deeply compares the positioning differences between the two and understands why skill systems are better suited to static file mode.

Learning Path

Encountering a problem?
    │
    ├─ Don't know how to use ──────────→ FAQ
    │                                 (concepts, configuration, usage tips)
    │
    ├─ Got an error ──────────────────→ Troubleshooting
    │                                 (error diagnosis, fix steps)
    │
    └─ Want to understand design ───────→ Why CLI?
                                      (technology selection, architecture decisions)

Recommended Order:

1. First read FAQ → Quickly understand core concepts and usage tips
2. Read Troubleshooting when you encounter errors → Find solutions by error message
3. Read design philosophy for deep understanding → Understand technical considerations of CLI vs MCP

Prerequisites

Recommended to Complete First

• Quick Start - Understand basic usage workflow
• Install OpenSkills - Ensure correct environment configuration

Next Steps

After completing this section, you can:

• Explore advanced features → Advanced Tutorials to learn Universal mode, custom skills, etc.
• Consult command reference → CLI API Reference for complete command documentation
• Learn about version updates → Changelog to view new features and changes

---

Quick Navigation

Question Type	Where to Find Answers
"What is OpenSkills?"	FAQ
"Where are skills installed?"	FAQ
"Git clone failed"	Troubleshooting
"SKILL.md not found"	Troubleshooting
"Why not use MCP?"	Why CLI?