OpenSkills Documentation

To create a skill, provide a SKILL.md file. You can include additional resources like scripts or assets in the same directory.

Minimal Structure:

my-skill/
└── SKILL.md

Structure with Resources:

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

SKILL.md Format: The file must include a YAML frontmatter with name and description.

---
name: pdf
description: Comprehensive PDF manipulation toolkit...
---

# PDF Skill Instructions
...

npx openskills install ./my-skill

If you are using multiple AI agents (e.g., Claude Code and Cursor) and want them to share a single AGENTS.md without conflicting with Claude's internal plugin marketplace, use the --universal flag. This installs skills to .agent/skills/ instead of .claude/skills/.

npx openskills install anthropics/skills --universal

To quickly set up OpenSkills in your project, install the Anthropic skills and then sync your AGENTS.md file to include the available skills metadata.

By default, skills are installed to ./.claude/skills. Use the --universal flag to install to ./.agent/skills for multi-agent compatibility, or --global to install to ~/.claude/skills.

npx openskills install anthropics/skills
npx openskills sync

OpenSkills allows you to install skills from the Anthropic marketplace, GitHub repositories, local paths, or private Git repositories.

# From Anthropic Marketplace
npx openskills install anthropics/skills

# From any GitHub Repo
npx openskills install your-org/your-skills

# From a Local Path
npx openskills install ./local-skills/my-skill

# From Private Git Repos
npx openskills install git@github.com:your-org/private-skills.git

When calling syncAgentsMd, you can provide a SyncOptions object to control the synchronization process.

The following commands are available via the OpenSkills CLI:

• install <source> [options]: Install from GitHub, local path, or private repo.
• sync [-y] [-o <path>]: Update AGENTS.md (or a custom output path) with the skills table.
• list: Show all installed skills.
• read <name>: Load a specific skill (used by agents to read instructions).
• update [name...]: Update installed skills (defaults to all).
• manage: Remove skills via an interactive interface.
• remove <name>: Remove a specific skill.

npx openskills install <source> [options]
npx openskills sync [-y] [-o <path>]
npx openskills list
npx openskills read <name>
npx openskills update [name...]
npx openskills manage
npx openskills remove <name>

Use these flags with the OpenSkills CLI commands:

• --global: Install globally to ~/.claude/skills (default is project-local).
• --universal: Install to .agent/skills/ instead of .claude/skills/.
• -y, --yes: Skip interactive prompts (useful for CI/CD).
• -o, --output <path>: Specify the output file for the sync command (default is AGENTS.md).

You can programmatically manage the .openskills.json file within a skill directory using the following utility functions:

• readSkillMetadata(skillDir: string): Attempts to read and parse the .openskills.json file in the specified directory. Returns a SkillSourceMetadata object if successful, or null if the file does not exist or is invalid.
• writeSkillMetadata(skillDir: string, metadata: SkillSourceMetadata): Writes the provided metadata to a .openskills.json file in the specified directory. If installedAt is not provided in the metadata object, it will be automatically set to the current ISO timestamp.

The updateSkills function can be called within a TypeScript/JavaScript environment to trigger the update process for installed skills.

Parameters:

• skillNames: A string, an array of strings, or undefined. If provided, only these specific skills will be updated. If undefined or empty, all installed skills are targeted.

Returns: Promise<void>

Behavior:

• Normalizes skill names.
• Identifies installed skills.
• For each target skill, it attempts to sync the files from the source (local path or git repository) to the installed path.
• Updates the installedAt timestamp in the skill's metadata upon success.

The manageSkills function provides an interactive CLI interface to select and remove installed skills. It lists all available skills, distinguishing between those located in the current project and those installed globally.

Users can select multiple skills via a checkbox interface. Once confirmed, the tool recursively removes the skill's directory from the filesystem. If the user cancels the prompt, the process exits gracefully.