Show HN：Sk` – 管理 Claude、Codex、OpenCode 等 AI 代理的技能

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

To see all available qualifiers, see our documentation.

Manage AI agent skills across Claude Code, Codex, OpenCode, and others using agents.toml

Uh oh!

There was an error while loading. Please reload this page.

803/skills-supply

Folders and files

Latest commit

History

Repository files navigation

sk

Manage AI agent skills across Claude Code, Codex, OpenCode, and others.

Highlights

Table of Contents

Installation

Quick Start

1. Initialize a manifest

Creates agents.toml with detected agents:

2. Add packages

sk auto-detects the package type from URLs. You can also be explicit:

3. Sync to your agents

Skills are now installed in each enabled agent's skills directory.

Core Concepts

Skills

A skill is a markdown file (SKILL.md) that extends what an AI agent can do. Skills contain instructions, patterns, workflows, or domain knowledge that agents follow during conversations.

Packages

A package is a collection of one or more skills. Packages can be:

Manifest

The manifest (agents.toml) declares which packages you want and which agents should receive them. It's the single source of truth for your skill configuration.

Agents

Agents are the AI coding tools that consume skills. Each agent has its own skills directory:

For global scope (--global), skills install to your home directory. For project scope (default), skills install within your project directory.

Dependencies

A dependency is a package declared in your manifest's [dependencies] section. When you run sk sync, each dependency is fetched and its skills are installed to your enabled agents.

Aliases

An alias is the name you give a dependency in your manifest—the key before the = sign:

Aliases must be unique within a manifest. Installed skills are prefixed with their alias to avoid conflicts: superpowers-debugging, superpowers-code-review, etc.

Project vs Global Scope

Project manifests are discovered by walking up from your current directory.

The Manifest

Package Types

sk supports several package types. You can specify them explicitly (sk pkg add gh ...) or let sk auto-detect from a URL (sk pkg add https://...).

URL auto-detection:

Claude Plugin (claude-plugin)

For plugins published to a Claude Code marketplace.

In your manifest:

How it works:

This is the key to cross-agent compatibility—plugins designed for Claude Code work with Codex and OpenCode too.

Marketplace formats:

Note: Marketplace plugins don't support --tag, --branch, --rev, or --path options.

Auto-detection: If you add a URL pointing to a marketplace repo, sk detects it and prompts you to select a plugin:

GitHub (gh)

For repositories hosted on GitHub.

Ref behavior:

Note: tag, branch, and rev are called "refs" (git references). Registry packages use semantic versions instead—see the Registry section when available.

Authentication: Uses your existing git SSH keys. For private repos, ensure your SSH key has access.

Git (git)

For any git remote—GitLab, Bitbucket, self-hosted, or SSH URLs.

Same ref options as GitHub packages (--tag, --branch, --rev).

When to use git vs gh:

Local Path (path)

For skills you're developing or testing locally.

Key behavior: Local packages are symlinked, not copied. When you edit files in the source directory, changes appear immediately in the agent's skills directory. No need to re-run sk sync.

This makes local packages ideal for:

Commands

Global Options

Creating Skill Packages

Package Structure

sk detects packages in several ways (checked in order):

For most new packages, use the subdirectory structure:

The SKILL.md File

Every skill needs a SKILL.md file with YAML frontmatter:

Requirements:

Manifest-Based Packages

For more control, add an agents.toml to your package:

This is useful when you want to:

Claude Code Plugins

sk automatically detects Claude Code plugins (packages with .claude-plugin/plugin.json). Skills from these plugins can be synced to all agents, not just Claude Code.

This means you can:

How It Works

Manifest Discovery

When you run sk sync, sk walks up from your current directory looking for agents.toml. The first manifest found is used. This means you can run sk sync from anywhere in your project.

For global scope (--global), sk uses ~/.sk/agents.toml directly.

Package Resolution

Each dependency in your manifest is resolved to a fetchable source:

Refs (tag, branch, rev) determine what gets checked out for git-based packages.

Skill Detection

After fetching, sk scans each package for skills (checked in order):

This means any GitHub, Git, or local package containing .claude-plugin/plugin.json is automatically treated as a plugin—you don't need to declare it as claude-plugin type. The explicit claude-plugin type is only needed for marketplace plugins.

Each discovered skill is validated (frontmatter, unique name).

Installation

Skills are installed to each enabled agent's skills directory:

Skill names are prefixed with the package alias to avoid conflicts: superpowers-debugging, feature-dev-code-review, etc.

State Tracking

sk maintains a state file (.sk-state.json) in each agent's root directory (e.g., ~/.claude/.sk-state.json for global, {project}/.claude/.sk-state.json for local). This tracks which skills sk installed, enabling:

Reconciliation

On each sync, sk compares the desired state (manifest) to the installed state:

This "npm prune" pattern ensures your installed skills always match your manifest.

Workflows

Team Setup

Share skills across your team:

Local Development

Develop skills with instant feedback:

CI/Automation

Install skills in CI pipelines:

Multiple Projects

Use global skills for tools you want everywhere, project skills for repo-specific needs:

Troubleshooting

"Skill target already exists and is not managed by sk"

sk found an existing skill with the same name that it didn't install. This protects manually-added skills from being overwritten.

Solutions:

"No dependencies to sync"

Your manifest has no packages in [dependencies].

Solutions:

Private repository access denied

sk uses your existing git SSH keys. For private repos:

Solutions:

Skills not appearing after sync

Check:

Changes to local skills not appearing

Local packages use symlinks, so changes should appear immediately. If not:

Check:

Resetting sk state

If you need to start fresh:

This makes sk treat all existing skills as unmanaged.

License

MIT

About

Manage AI agent skills across Claude Code, Codex, OpenCode, and others using agents.toml

Resources

Uh oh!

There was an error while loading. Please reload this page.

Stars

Watchers

Forks

Releases

  6

Languages

Footer

Footer navigation