add-skill 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,192 @@
+# add-skill
+
+Install agent skills onto your coding agents from any git repository.
+
+Supports [OpenCode](https://opencode.ai), [Claude Code](https://claude.ai/code), and [Codex](https://developers.openai.com/codex).
+
+## Quick Start
+
+```bash
+# Install a skill interactively
+npx add-skill openai/skills
+
+# Install a specific skill
+npx add-skill openai/skills --skill skill-creator
+
+# Install globally (available in all projects)
+npx add-skill openai/skills --skill linear -g
+```
+
+## What are Agent Skills?
+
+Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md` files with YAML frontmatter containing a `name` and `description`.
+
+Skills let agents perform specialized tasks like:
+- Generating release notes from git history
+- Creating PRs following your team's conventions
+- Integrating with external tools (Linear, Notion, etc.)
+
+## Usage
+
+### Source Formats
+
+The `<source>` argument accepts multiple formats:
+
+```bash
+# GitHub shorthand
+npx add-skill openai/skills
+
+# Full GitHub URL
+npx add-skill https://github.com/openai/skills
+
+# Direct path to a skill in a repo
+npx add-skill https://github.com/openai/skills/tree/main/skills/.system/skill-creator
+
+# GitLab URL
+npx add-skill https://gitlab.com/org/repo
+
+# Any git URL
+npx add-skill git@github.com:openai/skills.git
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Install to user directory instead of project |
+| `-a, --agent <agents...>` | Target specific agents: `opencode`, `claude-code`, `codex` |
+| `-s, --skill <skills...>` | Install specific skills by name |
+| `-l, --list` | List available skills without installing |
+| `-y, --yes` | Skip all confirmation prompts |
+| `-V, --version` | Show version number |
+| `-h, --help` | Show help |
+
+### Examples
+
+```bash
+# List skills in a repository
+npx add-skill openai/skills --list
+
+# Install multiple specific skills
+npx add-skill openai/skills --skill skill-creator --skill linear
+
+# Install to specific agents
+npx add-skill openai/skills -a claude-code -a opencode
+
+# Non-interactive installation (CI/CD friendly)
+npx add-skill openai/skills --skill linear -g -a claude-code -y
+
+# Install all skills from a repo
+npx add-skill openai/skills -y -g
+```
+
+## Installation Paths
+
+Skills are installed to different locations depending on the agent and scope:
+
+### Project-level (default)
+
+Installed in your current working directory. Commit these to share with your team.
+
+| Agent | Path |
+|-------|------|
+| OpenCode | `.opencode/skill/<name>/` |
+| Claude Code | `.claude/skills/<name>/` |
+| Codex | `.codex/skills/<name>/` |
+
+### Global (`--global`)
+
+Installed in your home directory. Available across all projects.
+
+| Agent | Path |
+|-------|------|
+| OpenCode | `~/.config/opencode/skill/<name>/` |
+| Claude Code | `~/.claude/skills/<name>/` |
+| Codex | `~/.codex/skills/<name>/` |
+
+## Agent Detection
+
+The CLI automatically detects which coding agents you have installed by checking for their configuration directories. If none are detected, you'll be prompted to select which agents to install to.
+
+## Creating Skills
+
+Skills are directories containing a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# My Skill
+
+Instructions for the agent to follow when this skill is activated.
+
+## When to Use
+
+Describe the scenarios where this skill should be used.
+
+## Steps
+
+1. First, do this
+2. Then, do that
+```
+
+### Required Fields
+
+- `name`: Unique identifier (lowercase, hyphens allowed)
+- `description`: Brief explanation of what the skill does
+
+### Skill Discovery
+
+The CLI searches for skills in these locations within a repository:
+
+- Root directory (if it contains `SKILL.md`)
+- `skills/`
+- `skills/.curated/`
+- `skills/.experimental/`
+- `skills/.system/`
+- `.codex/skills/`
+- `.claude/skills/`
+- `.opencode/skill/`
+
+If no skills are found in standard locations, a recursive search is performed.
+
+## Compatibility
+
+Skills are generally compatible across agents since they follow a shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
+
+| Feature | OpenCode | Claude Code | Codex |
+|---------|----------|-------------|-------|
+| Basic skills | Yes | Yes | Yes |
+| `allowed-tools` | Yes | Yes | Yes |
+| `context: fork` | No | Yes | No |
+| Hooks | No | Yes | No |
+
+## Troubleshooting
+
+### "No skills found"
+
+Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
+
+### Skill not loading in agent
+
+- Verify the skill was installed to the correct path
+- Check the agent's documentation for skill loading requirements
+- Ensure the `SKILL.md` frontmatter is valid YAML
+
+### Permission errors
+
+Ensure you have write access to the target directory.
+
+## Related Links
+
+- [OpenCode Skills Documentation](https://opencode.ai/docs/skills/)
+- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
+- [Codex Skills Documentation](https://developers.openai.com/codex/skills/)
+- [Agent Skills Specification](https://agentskills.io)
+- [OpenAI Skills Repository](https://github.com/openai/skills)
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "add-skill",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+
+    "@types/node": ["@types/node@25.0.8", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-powIePYMmC3ibL0UJ2i2s0WIbq6cg6UyVFQxSCpaPxxzAaziRfimGivjdF943sSGV6RADVbk0Nvlm5P/FB44Zg=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node