Skip to main content

​
Common Issues

This error occurs when the CLI cannot locate any valid SKILL.md files in the specified repository or path.Solution:
  • Ensure the repository contains SKILL.md files with proper YAML frontmatter
  • Verify that both name and description fields are present in the frontmatter
  • Check that the skill files are in one of the supported locations
Example of valid frontmatter:
---
name: my-skill
description: A brief description of what this skill does
---
Run npx skills add <repo> --list to see what skills the CLI can discover
If a skill was installed successfully but isn’t appearing in your agent, try these steps:Verify installation path:
  • Run npx skills list to see where the skill was installed
  • Check that the path matches your agent’s expected skills directory
  • Global skills install to ~/<agent>/skills/ (varies by agent)
  • Project skills install to ./<agent>/skills/
Check frontmatter validity:
  • Open the SKILL.md file and verify the YAML frontmatter is valid
  • Ensure there are no syntax errors (proper indentation, quotes, colons)
  • Both name and description must be strings
Agent-specific requirements:
  • Some agents may require a restart after installing skills
  • Check your agent’s documentation for skill loading requirements
  • Kiro CLI users must manually add skills to resources in .kiro/agents/<agent>.json
Kiro CLI users: After installing skills, add them to your custom agent’s resources:
{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}
Permission errors typically occur when you don’t have write access to the target installation directory.Solution:
  • Ensure you have write permissions for the target directory
  • For global installations (-g flag), verify your user can write to ~/<agent>/skills/
  • For project installations, ensure you have write access to the current directory
  • On Unix systems, check permissions with: ls -la <path>
If using symlinks (default method):
  • Some file systems don’t support symlinks (e.g., Windows without Developer Mode)
  • Use --copy flag to copy files instead: npx skills add <repo> --copy
When npx skills check or npx skills update fails, it’s usually due to:Skills installed from local paths:
  • Local skills cannot be checked for updates automatically
  • You’ll see a message: “Skipped (Local path)”
  • Manually reinstall to update: npx skills add <path> -g -y
Skills with no version tracking:
  • Older skills installed before lock file v3 may not have version hashes
  • Reinstall the skill to enable update tracking
GitHub API rate limits:
  • Set a GitHub token to increase rate limits: 
    export GITHUB_TOKEN=your_token_here
  • Or use GitHub CLI: gh auth login
If multiple skills have the same name in their frontmatter:
  • The CLI will skip duplicate names and only install the first one found
  • Check skill names with: npx skills add <repo> --list
  • Use the --skill flag to install a specific skill by name
For skill authors:
  • Ensure your skill names are unique within your repository
  • Use descriptive, kebab-case names: my-awesome-skill
Skills marked as internal: true are hidden by default.To view and install internal skills:
INSTALL_INTERNAL_SKILLS=1 npx skills add <repo> --list
Why are skills marked internal?
  • Work-in-progress skills
  • Internal tooling not meant for public use
  • Experimental features under development
Internal skills may change or break without notice. Use with caution.

​
Environment Variables

The Skills CLI respects these environment variables:
VariableDescription
INSTALL_INTERNAL_SKILLSSet to 1 or true to show and install skills marked as internal: true
DISABLE_TELEMETRYSet to disable anonymous usage telemetry
DO_NOT_TRACKAlternative way to disable telemetry
GITHUB_TOKENGitHub personal access token for higher API rate limits
CLAUDE_CONFIG_DIRCustom Claude Code config directory (default: ~/.claude)
CODEX_HOMECustom Codex home directory (default: ~/.codex)

​
Getting Help

If you’re still experiencing issues:

View Examples

Check the quickstart guide for common usage patterns

Check Compatibility

Verify your agent supports the feature you’re trying to use

Report an Issue

File a bug report on GitHub

Community

Browse skills and get community support

Build docs developers (and LLMs) love

Get started for freeTalk to us