ask

README

ASK: Agent Skills Kit

Just ask, and your agent shall receive.

Quick Start · Commands · Sources · Docs

English | 中文

---

ASK (Agent Skills Kit) is the package manager for AI Agent Skills. Just like brew manages macOS packages or npm manages Node.js dependencies, ask helps you discover, install, and manage capabilities for your AI agents.

graph LR
    User[User/Agent] -->|ask skill search| Sources[GitHub/MCP/Community]
    Sources -->|Discover| Skills{Skills}
    User -->|ask skill install| Skills
    Skills -->|Download & Lock| Agent[.agent/skills/]
    
    style User fill:#4a9eff,color:white
    style Sources fill:#ff6b6b,color:white
    style Agent fill:#90ee90,color:black

✨ Key Features

📦 Smart Package Management

Install, uninstall, update, and list skills with intuitive commands. Version locking via ask.lock ensures reproducible environments across teams.

🔍 Multi-Source Discovery

Search skills from multiple sources simultaneously — community topics, official repositories, and scientific domains. See which skills you already have installed.

⚡ Lightning Fast

Built with Go, compiling to a single static binary with zero runtime dependencies. Parallel search across all sources. Git sparse checkout for minimal downloads.

🔒 Version Locking

Pin specific versions with skill@v1.0 syntax. Track exact commits in ask.lock for reproducible installations.

📊 Progress Tracking

Real-time progress bars during installation and updates. Clear feedback on what's happening.

🔌 Offline Mode

Use --offline flag to work without network. Search uses cached results; perfect for air-gapped environments.

🤖 Multi-Tool Support

Automatically detects and supports skills directories for Claude Code (.claude/skills), Cursor (.cursor/skills), OpenAI Codex (.codex/skills), and OpenCode (.opencode/skills). Simply run ask skill install and it will install to all detected tool directories.

🌍 Global Installation

Install skills globally with --global flag to share across all projects. Local project installations take precedence over global ones.

---

🚀 Quick Start

① Install ASK

# macOS (Homebrew)
brew tap yeasy/ask
brew install ask

# Or build from source
git clone https://github.com/yeasy/ask.git && cd ask
make build && mv ask /usr/local/bin/

② Initialize Your Project

ask init    # Creates ask.yaml in current directory

③ Search & Install Skills

ask skill search browser      # Search across all sources
ask skill install browser-use           # Install a skill
ask skill install skill1 skill2 skill3  # Install multiple skills
ask skill list                # View installed skills

---

📋 Commands

Command	Description
ask init	Initialize project, create ask.yaml
Skill Management
ask skill search <keyword>	Search skills across all sources
ask skill install <skill...>	Install skill(s) to ./skills/
ask skill install skill@v1.0	Install specific version
ask skill uninstall <skill>	Remove a skill
ask skill list	List installed skills
ask skill info <skill>	Show skill details
ask skill update [skill]	Update skill(s) to latest
ask skill outdated	Check for updates
ask skill create <name>	Create new skill template
Repository Management
ask repo list [name]	List repos or skills in repo
ask repo add <url>	Add custom source
ask repo remove <name>	Remove a source
Shell Completion
ask completion <shell>	Generate completion script
Utilities
ask benchmark	Run performance benchmarks
--offline	Global flag: run without network
--global, -g	Global flag: use global installation (~/.ask/skills)

---

🌐 Skill Sources

ASK searches these sources by default:

Source	Type	Description
Community	topic	GitHub repos with agent-skill topic
Anthropics	dir	Official anthropics/skills
MCP-Servers	dir	modelcontextprotocol/servers
Scientific	dir	Research skills from K-Dense-AI
Superpowers	dir	Core skills from obra/superpowers
OpenAI	dir	Codex skills from openai/skills

Add Custom Sources

# ask.yaml
repos:
  - name: my-team
    type: dir
    url: my-org/agent-skills/skills

---

📂 Project Structure

After using ASK, your project looks like:

my-agent/
├── ask.yaml          # Manifest file
├── ask.lock          # Version lock file
├── main.py           # Your agent code
└── .agent/
    └── skills/       # Project-level skills
        ├── browser-use/
        └── web-surfer/

# Global skills (shared across projects)
~/.ask/
├── config.yaml       # Global config
├── ask.lock          # Global version lock
└── skills/           # Global skills
    └── shared-skill/

Installation Scopes

# Project-level (default) - stored in .agent/skills/
ask skill install browser-use

# Multi-Agent Installation
ask skill install browser-use --agent claude --agent cursor

# Global - stored in ~/.ask/skills/, available to all projects
ask skill install --global shared-skill
ask skill install -g shared-skill

# Global for specific agent
ask skill install browser-use --agent claude --global
# Installs to ~/.claude/skills/

# List both
ask skill list --all

# List for specific agent
ask skill list --agent claude

---

## 🛠 Development

```bash
make build     # Build binary
make test      # Run tests
make fmt       # Format code
make vet       # Check code
make install   # Install to $GOPATH/bin

Shell Completion

Enable tab completion for faster workflows:

# Bash
ask completion bash > /usr/local/etc/bash_completion.d/ask

# Zsh
ask completion zsh > "${fpath[1]}/_ask"

# Fish
ask completion fish > ~/.config/fish/completions/ask.fish

# PowerShell
ask completion powershell > ask.ps1

---

📚 Documentation

See the docs/ directory for detailed documentation:

• Installation Guide
• Command Reference
• Skill Sources
• SKILL.md Format
• Configuration
• Troubleshooting
• Architecture

---

🤝 Contributing

We welcome contributions! Please see our Contribution Guidelines.

---

📄 License

MIT