v0.2.0: CLI restructure, configurable skills_dir, add OpenAI repo

Author: yeasy

README.md

@@ -9,10 +9,18 @@
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#usage">Usage</a> •
-  <a href="#contributing">Contributing</a>
+  <a href="https://github.com/yeasy/ask/releases"><img src="https://img.shields.io/github/v/release/yeasy/ask?style=flat-square&color=blue" alt="Release"></a>
+  <a href="https://github.com/yeasy/ask/blob/main/LICENSE"><img src="https://img.shields.io/github/license/yeasy/ask?style=flat-square" alt="License"></a>
+  <a href="https://github.com/yeasy/ask/stargazers"><img src="https://img.shields.io/github/stars/yeasy/ask?style=flat-square" alt="Stars"></a>
+  <a href="https://github.com/yeasy/ask/actions"><img src="https://img.shields.io/github/actions/workflow/status/yeasy/ask/release.yml?style=flat-square" alt="Build"></a>
+  <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat-square&logo=go" alt="Go Version">
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> · 
+  <a href="#-commands">Commands</a> · 
+  <a href="#-skill-sources">Sources</a> · 
+  <a href="docs/README.md">Docs</a>
 </p>
 
 <p align="center">
@@ -21,125 +29,151 @@
 
 ---
 
-**ASK** (Agent Skills Kit) is a command-line interface (CLI) designed to be the package manager for AI Agent Skills. Similar to how `brew` manages macOS packages or `npm` manages Node.js dependencies, `ask` helps you discover, install, and manage capabilities for your AI agents.
+**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.
+
+## ✨ 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.
 
-## Features
+### ⚡ 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.
 
-- **📦 Package Management**: Install, uninstall, and list skills with ease.
-- **🔍 Discovery**: Search GitHub for skills from multiple sources (topic-based and directory-based).
-- **🌐 Multiple Sources**: Built-in support for the `agent-skill` topic and [Anthropics Skills](https://github.com/anthropics/skills).
-- **⚡️ Fast & Native**: Built with Go, compiling to a single static binary with no runtime dependencies.
-- **🛠 Project-Local**: Manages dependencies via `ask.yaml`, keeping your projects reproducible.
+### 🔒 Version Locking
+Pin specific versions with `skill@v1.0` syntax. Track exact commits in `ask.lock` for reproducible installations.
 
-## Installation
+### 📊 Progress Tracking
+Real-time progress bars during installation and updates. Clear feedback on what's happening.
+
+---
+
+## 🚀 Quick Start
+
+**① Install ASK**
 
-### macOS (Homebrew)
 ```bash
+# 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/
 ```
 
-### Manual
-Download the latest release from the [Releases](https://github.com/yeasy/ask/releases) page, or build from source:
+**② Initialize Your Project**
 
 ```bash
-git clone https://github.com/yeasy/ask.git
-cd ask
-make build
-mv ask /usr/local/bin/
+ask init    # Creates ask.yaml in current directory
 ```
 
-## Usage
+**③ Search & Install Skills**
 
-### 1. Initialize a Project
-Start by initializing `ask` in your agent's root directory:
 ```bash
-ask init
+ask skill search browser      # Search across all sources
+ask skill install browser-use # Install a skill
+ask skill list                # View installed skills
 ```
-This creates an `ask.yaml` file to track your skills.
 
-### 2. Search for Skills
-Find skills relevant to your needs:
-```bash
-ask search browser
-# Returns skills like: browser-use, web-surfer, etc.
-```
+---
 
-### 3. Install a Skill
-Install a skill directly from GitHub:
-```bash
-ask install browser-use/browser-use
-```
-This will:
-- Clone the repository into `./skills/browser-use`
-- Add the dependency to `ask.yaml`
+## 📋 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 a skill 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` | List skill sources |
+| `ask repo add <url>` | Add custom source |
+| `ask repo remove <name>` | Remove a source |
 
-### 4. Uninstall a Skill
-Remove a skill you no longer need:
-```bash
-ask uninstall browser-use
-```
-or
-```bash
-ask uninstall browser-use/browser-use
-```
-This will:
-- Remove the directory `skills/browser-use`
-- Remove the dependency from `ask.yaml`
+---
 
-### 5. List Installed Skills
-See what your agent is equipped with:
-```bash
-ask list
+## 🌐 Skill Sources
+
+ASK searches these sources by default:
+
+| Source | Type | Description |
+|--------|------|-------------|
+| **Community** | topic | GitHub repos with `agent-skill` topic |
+| **Anthropics** | dir | Official [anthropics/skills](https://github.com/anthropics/skills) |
+| **MCP-Servers** | dir | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
+| **Scientific** | dir | Research skills from [K-Dense-AI](https://github.com/K-Dense-AI/claude-scientific-skills) |
+| **Superpowers** | dir | Core skills from [obra/superpowers](https://github.com/obra/superpowers) |
+| **OpenAI** | dir | Codex skills from [openai/skills](https://github.com/openai/skills) |
+
+### Add Custom Sources
+
+```yaml
+# ask.yaml
+repos:
+  - name: my-team
+    type: dir
+    url: my-org/agent-skills/skills
 ```
 
-## Directory Structure
-When you use `ask`, your project will look like this:
+---
+
+## 📂 Project Structure
+
+After using ASK, your project looks like:
 
-```text
+```
 my-agent/
 ├── ask.yaml          # Manifest file
+├── ask.lock          # Version lock file
 ├── main.py           # Your agent code
-└── skills/           # Managed skills directory
-    ├── browser-use/
-    └── web-surfer/
+└── .agent/
+    └── skills/       # Managed skills
+        ├── browser-use/
+        └── web-surfer/
 ```
 
-## Skill Sources
-By default, `ask` searches these sources:
-
-1. **Community** (`topic`): GitHub repos with the `agent-skill` topic.
-2. **Anthropics** (`dir`): Skills from [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills).
+---
 
-You can customize sources in your `ask.yaml`:
+## 🛠 Development
 
-```yaml
-version: "1.0"
-skills:
-  - browser-use
-sources:
-  - name: community
-    type: topic
-    url: agent-skill
-  - name: anthropics
-    type: dir
-    url: anthropics/skills/skills
+```bash
+make build     # Build binary
+make test      # Run tests
+make fmt       # Format code
+make vet       # Check code
+make install   # Install to $GOPATH/bin
 ```
 
-## Development
-This project includes a `Makefile` to simplify common development tasks:
+---
+
+## 📚 Documentation
+
+See the [docs/](docs/README.md) directory for detailed documentation:
+
+- [Installation Guide](docs/installation.md)
+- [Command Reference](docs/commands.md)
+- [Skill Sources](docs/skill-sources.md)
+- [SKILL.md Format](docs/skill-format.md)
+- [Configuration](docs/configuration.md)
 
-- `make build`: Compiles the binary to `ask`.
-- `make test`: Runs unit tests.
-- `make clean`: Removes the binary and runs `go clean`.
-- `make run`: Runs `go run main.go`.
-- `make deps`: Downloads dependencies (`go mod download`).
-- `make fmt`: Formats code (`go fmt ./...`).
-- `make vet`: Vets code (`go vet ./...`).
-- `make install`: Installs the binary to `$GOPATH/bin` (`go install`).
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contribution Guidelines](CONTRIBUTING.md).
+
+---
 
-## Contributing
-We welcome contributions! Please check out our [Contribution Guidelines](CONTRIBUTING.md).
+## 📄 License
 
-## License
 MIT