SK / agent-skill-porter

A skill lifecycle management CLI for AI agents — Add and manage updates for any Skill, and convert formats across Claude Code and many other agents. Zero config, no extra files needed.

Installation

pnpm add -g agent-skill-porter

Quick Start

Add a skill from GitHub

# Add skills to your local project
sk add https://github.com/anthropics/skills

# Check for upstream updates
sk update -n

# Apply upstream updates
sk update

# Add a specific skill to a specific agent's directory (to ./.claude/skills/)
sk add https://github.com/anthropics/skills/tree/main/skills/skill-creator claude

# Place into user-level (global) directory (to ~/.claude/skills/)
sk add https://github.com/anthropics/skills/tree/main/skills/skill-creator claude -g

# Preview only, without downloading (dry run)
sk add https://github.com/anthropics/skills -n

Reformat and relocate skills for other agents

# Convert skill format and placement from Claude to Gemini
sk sync claude gemini

# Convert in both directions
sk sync gemini claude

# Convert skills in user-level (global) directories
sk sync gemini claude -g

# Preview changes before applying
sk sync gemini claude -n

Supported Agents

Features

• Add from GitHub — Fetch skills directly from GitHub repositories with sk add
• Update from Upstream — Check and apply upstream changes to downloaded skills with sk update
• List Skills — List all skills across agents with sk list
• Skill Info — View skill metadata and source links with sk info
• Provenance Tracking — Every add and sync records the source in _from (as owner/repo@shortHash, 7-char SHA by default; use --full-hash for full 40-char SHA). If a public skill is found to be compromised, trace affected local skills instantly. Disable with --no-provenance
• Cross-Agent Conversion — Convert skill formats and placement across 7 agents, absorbing format differences automatically
• Placeholder Conversion — $ARGUMENTS ↔ {{args}}, file references, shell commands auto-converted
• Dry-Run Preview — Preview changes with -n before applying them
• Lossless Conversion — Chimera Hub — Preserves all agent-specific settings across round-trip conversions (details)

FAQ

What does _from mean, and when should I use --no-provenance?

_from records where a skill came from (typically owner/repo@shortHash) so you can trace local copies if an upstream public skill is later found to be compromised. Use --no-provenance when you do not want that metadata written into frontmatter—for example, internal mirrors or policies that discourage embedding repository references.

Why does sk write under my repo instead of ~/.claude?

Inside a Git repository, sk defaults to project-level paths (for example <repo>/.claude/skills) so skills live with the codebase. Use -g / --global for user-level directories, or --{agent}-dir for a custom base path. See Directory Resolution below.

Why is there no xxx.config.js-style configuration file?

We intentionally avoid adding another config file at the repository root. Zero config, no extra files is a core product principle.

Why not track provenance with a lock file (like Vercel's agent-skills)?

For the same reason: we do not want extra root-level files. SKILL.md already uses YAML frontmatter for metadata; a small amount of extra information there (for example _from) is enough. Token overhead stays minimal. Zero config, no extra files remains the guiding idea.

Is it OK to add custom properties to SKILL.md frontmatter?

Yes. The Agent Skills standard is shared across tools, but there is no ban on extra YAML frontmatter keys. In practice, vendors extend SKILL.md with their own fields, and unknown properties are generally ignored. The cost is typically on the order of 10–20 tokens per skill—even with dozens of skills in a project, the impact is minor.

Subcommands

sk add <url> [to] (alias: sk download) — Add a skill from GitHub

sk add https://github.com/anthropics/skills/tree/main/skills/skill-creator
sk add <url> gemini                       # Place in Gemini skill directory
sk add <url> claude -g                    # Place in global Claude directory
sk add <url> -n                           # Preview without downloading

GitHub Authentication

For private repositories, set a personal access token:

export GITHUB_TOKEN=ghp_...

Token permissions: Public repositories require no permissions. For private repositories, grant Contents: Read access to the target repository.

sk update [skill-path] — Update downloaded skills from upstream

sk update                                 # Check and update all agent skills
sk update .claude/skills/my-skill         # Update a specific skill
sk update skills/                         # Update all skills under a path
sk update -n                              # Check for updates without applying

sk list (alias: sk ls) — List skills across all agents

sk list                                   # List project-level skills
sk list -g                                # List global (user-level) skills

sk info [skill-path] — Show skill information

sk info                                   # Interactively select and view a skill
sk info .claude/skills/my-skill           # Show skill info and source links
sk info .claude/skills/my-skill/SKILL.md  # SKILL.md path also accepted

sk sync <from> <to> — Direct conversion between agents

sk sync claude gemini                     # Convert Claude → Gemini
sk sync claude gemini -t commands          # Commands only

sk import <agent> / sk apply <agent> — Lossless conversion workflow

sk import claude                          # Import Claude → Chimera Hub
sk import gemini -t commands              # Import commands only
sk apply gemini                           # Apply Chimera Hub → Gemini
sk apply claude --remove-unsupported      # Remove unsupported fields

sk drift <agent> / sk plan <agent> — Preview (dry run)

sk drift claude                           # Preview import changes
sk plan gemini                            # Preview apply changes

sk migrate — Migrate Chimera Hub directories from .acs/.asp to .agent-skill-porter

sk migrate                                # Rename .acs/.asp → .agent-skill-porter (user-level + project-level)

Options (sync subcommand)

Examples

# Direct conversion with preview
sk sync claude gemini -n

# Convert specific file
sk sync gemini claude -f analyze-code

# Chimera hub workflow
sk import claude                          # Import Claude → Chimera
sk import gemini                          # Import Gemini → Chimera (merges)
sk apply claude                           # Apply Chimera → Claude (with Claude extras)
sk apply gemini                           # Apply Chimera → Gemini (with Gemini extras)

# Full sync with cleanup
sk sync claude gemini --sync-delete --remove-unsupported

# Use custom directories
sk sync claude gemini --claude-dir ~/my-claude --gemini-dir ~/my-gemini

# Show verbose output for debugging
sk sync claude gemini -v

Directory Resolution

When running inside a Git repository, sk defaults to project-level directories (e.g., <repo>/.claude, <repo>/.gemini). Use -g/--global to use user-level directories instead.

Priority order:

1. --{agent}-dir (custom directory) — always takes precedence
2. Project-level — default when inside a Git repository
3. User-level — default when outside a Git repository, or when -g is specified

Project-level (default inside Git repos)

User-level (with -g or outside Git repos)

Skills Format

Skills follow the Agent Skills open standard adopted by Claude Code, Gemini CLI, Codex CLI, OpenCode, and Cursor.

Directory Structure

Each skill is a directory containing SKILL.md and optional support files:

~/.claude/skills/
└── my-skill/
    ├── SKILL.md           # Main skill definition (required)
    ├── helper.sh          # Support file (optional)
    └── config.json        # Support file (optional)

SKILL.md Format

All tools use the same SKILL.md format with YAML frontmatter:

---
name: my-skill
description: A helpful skill description
---

Skill instructions go here.

Use $ARGUMENTS for user input.

Skill Metadata Comparison

* Codex uses policy.allow_implicit_invocation in agents/openai.yaml (inverted logic)
** OpenCode uses disable-model-invocation directly in SKILL.md frontmatter
*** Copilot uses user-invokable (with 'k') instead of Claude's user-invocable (with 'c'); automatically normalized during conversion

Codex-Specific: agents/openai.yaml

Codex CLI supports an optional agents/openai.yaml configuration file:

~/.codex/skills/
└── my-skill/
    ├── SKILL.md
    └── agents/
        └── openai.yaml    # Codex-specific configuration

Example openai.yaml:

interface:
  display_name: "My Skill"
  short_description: "A skill description"
policy:
  allow_implicit_invocation: true

Model Invocation Control Conversion

The policy.allow_implicit_invocation field in Codex is converted to/from Claude's disable-model-invocation with inverted logic:

When converting Claude → Codex with disable-model-invocation set, an agents/openai.yaml file is automatically generated.

Other openai.yaml fields (interface.display_name, interface.short_description) are Codex-specific and not converted.

Support Files

Support files (scripts, configs, images, etc.) are copied as-is during conversion:

Placeholder Conversion (Skills)

Same as Commands:

Advanced Reference

For detailed documentation on the following topics, see Advanced Reference:

• Lossless Conversion — Chimera Hub — Preserves all agent-specific settings across round-trip conversions (details)
• Commands — Single-file slash command format details, metadata comparison, and placeholder syntax
• Architecture — Semantic IR design, body tokenization, and source layout

Official Documents

Commands

• Slash commands - Claude Docs
• gemini-cli/docs/cli/custom-commands.md at main · google-gemini/gemini-cli
• codex/docs/prompts.md at main · openai/codex
• OpenCode
• Custom instructions for GitHub Copilot

Skills

• Agent Skills Standard
• Custom skills - Claude Docs

Status Indicators

• [A] Created (Green) - New files created in target directory
• [M] Modified (Yellow) - Existing files updated
• [=] Unchanged (Blue) - File exists and converted content is identical
• [D] Deleted (Red) - Files removed with --sync-delete
• [-] Skipped (Gray) - Files skipped with --no-overwrite

Requirements

• Node.js >= 24.0.0
• pnpm >= 10

Development

See Development Guide for build, test, lint, and publishing instructions.

CHANGELOG

CHANGELOG.md

[!NOTE]
The asp, acs, and agent-command-sync commands are deprecated. Use sk or agent-skill-porter instead.

License

MIT