felo-ai 0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,346 @@
+# Contributing to Felo Skills
+
+We welcome contributions! Whether you want to report bugs, suggest features, improve documentation, or add new skills.
+
+---
+
+## How to Contribute
+
+### 1. Report Bugs
+
+Found a bug? [Open an issue](https://github.com/Felo-Inc/felo-skills/issues/new) with:
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment (OS, Claude Code version, skill version)
+- Error messages or logs
+
+### 2. Suggest Features
+
+Have an idea? [Start a discussion](https://github.com/Felo-Inc/felo-skills/discussions) or open an issue with:
+- Use case description
+- Why this feature is useful
+- Proposed implementation (optional)
+
+### 3. Submit Code
+
+Ready to code? Follow the pull request process below.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Git
+- Claude Code CLI
+- Node.js (for testing npx installation)
+- Text editor
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/Felo-Inc/felo-skills.git
+cd felo-skills
+```
+
+### Test Locally
+
+Copy a skill to your Claude Code skills directory:
+
+```bash
+# Linux/macOS
+cp -r felo-search ~/.claude/skills/
+
+# Windows (PowerShell)
+Copy-Item -Recurse felo-search "$env:USERPROFILE\.claude\skills\"
+```
+
+Restart Claude Code:
+```bash
+claude restart
+```
+
+Test the skill:
+```
+Ask Claude: "What's the weather today?"
+```
+
+---
+
+## Adding a New Skill
+
+### Folder Structure
+
+Create a new folder for your skill:
+
+```
+your-skill-name/
+├── SKILL.md          # Skill implementation (required)
+├── README.md         # User documentation (required)
+└── LICENSE           # MIT License (required)
+```
+
+### SKILL.md Format
+
+The `SKILL.md` file defines how the skill works. Use this template:
+
+```markdown
+---
+name: your-skill-name
+description: "Brief description of when to use this skill. Include trigger keywords and use cases."
+---
+
+# Your Skill Name
+
+## When to Use
+
+List specific scenarios when this skill should trigger:
+- Scenario 1
+- Scenario 2
+- Trigger keywords: "keyword1", "keyword2"
+
+## Setup
+
+Step-by-step setup instructions:
+1. Get API key from [service]
+2. Set environment variable
+3. Test the skill
+
+## How to Execute
+
+Detailed instructions for Claude Code on how to execute this skill:
+
+### Step 1: Check Prerequisites
+[Bash commands to verify setup]
+
+### Step 2: Execute Main Logic
+[Bash commands or tool calls to perform the skill's function]
+
+### Step 3: Format Response
+[How to present results to the user]
+
+## Examples
+
+### Example 1: [Scenario]
+**User asks:** "example query"
+**You MUST do:** [step-by-step execution]
+
+## Error Handling
+
+Common errors and solutions:
+- Error 1: Solution
+- Error 2: Solution
+
+## Important Notes
+
+- Key implementation details
+- Best practices
+- Limitations
+```
+
+### README.md Format
+
+User-facing documentation. Use this structure:
+
+```markdown
+# Your Skill Name
+
+**One-line description**
+
+Brief overview of what the skill does.
+
+---
+
+## What It Does
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+**When to use:**
+- Use case 1
+- Use case 2
+
+**When NOT to use:**
+- Anti-pattern 1
+- Anti-pattern 2
+
+---
+
+## Quick Setup
+
+### Step 1: Install
+[Installation command]
+
+### Step 2: Configure
+[Configuration steps with verification]
+
+### Step 3: Test
+[Test command]
+
+---
+
+## Usage Examples
+
+[Real-world examples with input/output]
+
+---
+
+## Troubleshooting
+
+[Common issues and solutions]
+
+---
+
+## Links
+
+- [Service website]
+- [API documentation]
+- [Report issues]
+```
+
+### Testing Checklist
+
+Before submitting, verify:
+
+- [ ] Skill triggers correctly for intended scenarios
+- [ ] Error handling works (missing API key, network errors, etc.)
+- [ ] Multi-language support (if applicable)
+- [ ] Documentation is clear and complete
+- [ ] Examples are realistic and helpful
+- [ ] All commands are copy-paste ready
+- [ ] Links work
+- [ ] Tested on Windows, macOS, or Linux
+
+---
+
+## Pull Request Guidelines
+
+### Branch Naming
+
+Use descriptive branch names:
+- `feature/add-xyz-skill` - New skill
+- `fix/felo-search-encoding` - Bug fix
+- `docs/improve-readme` - Documentation
+- `refactor/skill-structure` - Code refactoring
+
+### Commit Messages
+
+Follow this format:
+```
+type: brief description
+
+Detailed explanation (if needed)
+```
+
+Types:
+- `feat`: New feature or skill
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `refactor`: Code refactoring
+- `test`: Testing improvements
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat: add weather-skill for real-time weather data
+
+Integrates OpenWeatherMap API to provide current weather,
+forecasts, and alerts. Supports multi-language queries.
+
+fix: handle Chinese characters in felo-search
+
+Use heredoc for JSON files to properly encode Chinese,
+Japanese, and Korean characters.
+
+docs: improve installation guide in README
+
+Add verification steps after each installation step
+to help users confirm setup is correct.
+```
+
+### Pull Request Description
+
+Include:
+
+1. **What**: What does this PR do?
+2. **Why**: Why is this change needed?
+3. **How**: How does it work?
+4. **Testing**: How did you test this?
+5. **Screenshots**: (if applicable)
+
+Example:
+```markdown
+## What
+Adds a new skill for real-time weather information using OpenWeatherMap API.
+
+## Why
+Users frequently ask about weather, and current web search is slow.
+Direct API integration provides faster, more accurate results.
+
+## How
+- Integrates OpenWeatherMap API
+- Auto-triggers for weather-related queries
+- Supports location detection and multi-language
+
+## Testing
+- Tested on Windows 11, macOS 14, Ubuntu 22.04
+- Verified with English, Chinese, Japanese queries
+- Tested error handling (invalid API key, network errors)
+
+## Screenshots
+[Screenshot of weather query result]
+```
+
+### Review Process
+
+1. Submit PR
+2. Automated checks run (if configured)
+3. Maintainers review code and documentation
+4. Address feedback
+5. PR merged
+
+---
+
+## Code of Conduct
+
+### Be Respectful
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints
+- Accept constructive criticism gracefully
+- Focus on what's best for the community
+
+### Be Professional
+
+- Keep discussions on-topic
+- Avoid personal attacks
+- Don't spam or self-promote
+- Follow GitHub's terms of service
+
+### Be Helpful
+
+- Help newcomers get started
+- Share knowledge and experience
+- Provide constructive feedback
+- Celebrate others' contributions
+
+---
+
+## Questions?
+
+- **Documentation**: Check [README](./README.md) and skill docs
+- **Discussions**: [GitHub Discussions](https://github.com/Felo-Inc/felo-skills/discussions)
+- **Issues**: [GitHub Issues](https://github.com/Felo-Inc/felo-skills/issues)
+- **Email**: support@felo.ai
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to Felo Skills! 🎉

package/README.en.md

@@ -0,0 +1,87 @@
+# Felo AI
+
+**Ask anything. Get current answers powered by AI.**
+
+Felo AI provides a terminal CLI and Claude Code skill, with support for English, Chinese (Simplified & Traditional), Japanese, and Korean.
+
+[![License](https://img.shields.io/badge/license-MIT-green)]()
+
+---
+
+## Two Core Capabilities
+
+Felo AI offers two main features: **Real-time Search** and **PPT Generation**. Use them via the CLI in your terminal, or in Claude Code via the skill (search can trigger automatically).
+
+### Capability 1: Real-time Search
+
+Search the web for up-to-date information and get AI-synthesized answers. Ideal for weather, news, prices, documentation, tech updates, and any question that needs “right now” information.
+
+- **Multi-language**: Ask in your preferred language.
+- **Terminal**: `felo search "your question"`
+- **Claude Code**: After installing the skill, it triggers automatically, or type `/felo-ai your question`
+- **Examples**: `felo search "Tokyo weather"`, `felo search "React 19 new features" --verbose`
+
+### Capability 2: Generate PPT
+
+Describe a topic in one sentence and Felo generates a slideshow. The job runs in the cloud; when done, you get an **online document link** to open in your browser.
+
+- **Terminal**: `felo slides "your topic or description"`
+- **Examples**: `felo slides "Felo product intro, 3 slides"`, `felo slides "Introduction to React" --poll-timeout 300`
+
+---
+
+## Install & Configure
+
+### Install CLI
+
+```bash
+npm install -g felo-ai
+```
+
+Run without installing: `npx felo-ai search "Tokyo weather"`  
+After install, the command is `felo`.
+
+### Configure API Key
+
+Recommended (persisted):
+
+```bash
+felo config set FELO_API_KEY your-api-key-here
+```
+
+Or set the environment variable: `export FELO_API_KEY="your-api-key-here"` (Linux/macOS), `$env:FELO_API_KEY="your-api-key-here"` (Windows PowerShell).
+
+Get your API key at [felo.ai](https://felo.ai) (Settings → API Keys).
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `felo search "<query>"` | Real-time search |
+| `felo slides "<prompt>"` | Generate PPT |
+| `felo config set FELO_API_KEY <key>` | Save API key |
+| `felo config get/list/path/unset` | View / list / path / remove config |
+
+---
+
+## Claude Code Skill
+
+Install the skill:
+
+```bash
+npx @claude/skills add felo-ai
+```
+
+After setting `FELO_API_KEY`, ask Claude things like “What’s the weather in Tokyo today?” or “React 19 new features” and search will trigger automatically. PPT generation is available only via the terminal with `felo slides`.
+
+---
+
+## Links
+
+- [Felo Open Platform](https://openapi.felo.ai/docs/) — Get your API key
+- [API Documentation](https://openapi.felo.ai/docs/api-reference/v2/chat.html)
+- [More examples](./docs/EXAMPLES.md) | [FAQ](./docs/FAQ.md) | [GitHub Issues](https://github.com/Felo-Inc/felo-skills/issues)
+
+---
+
+**Other languages / 其他语言:** [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [繁體中文](README.zh-TW.md)

package/README.ja.md

@@ -0,0 +1,87 @@
+# Felo AI
+
+**何でも聞いて、AI で今の答えを。**
+
+Felo AI はターミナル用 CLI と Claude Code スキルを提供し、日本語・英語・中国語（簡体・繁体）・韓国語に対応しています。
+
+[![License](https://img.shields.io/badge/license-MIT-green)]()
+
+---
+
+## 2つの機能
+
+Felo AI のコア機能は **リアルタイム検索** と **PPT 生成** です。ターミナルの CLI で使うほか、Claude Code のスキルとしても利用でき、検索は自動で発動します。
+
+### 機能1: リアルタイム検索
+
+最新情報を検索し、AI がまとめた回答を取得します。天気、ニュース、価格、ドキュメント、技術動向など、「今」の情報が必要なときに最適です。
+
+- **多言語対応**: お好みの言語で質問できます。
+- **ターミナル**: `felo search "質問"`
+- **Claude Code**: スキル導入後は自動で発動。手動では `/felo-ai 質問`
+- **例**: `felo search "東京の天気"`、`felo search "React 19 new features" --verbose`
+
+### 機能2: PPT 生成
+
+テーマや説明を一文で指定すると、PPT を自動作成します。処理はクラウドで実行され、完了後に**オンライン文書リンク**が返り、ブラウザで開いて確認・編集できます。
+
+- **ターミナル**: `felo slides "テーマや説明"`
+- **例**: `felo slides "Felo 製品紹介、3枚"`、`felo slides "Introduction to React" --poll-timeout 300`
+
+---
+
+## インストールと設定
+
+### CLI のインストール
+
+```bash
+npm install -g felo-ai
+```
+
+インストールせずに実行: `npx felo-ai search "東京の天気"`  
+インストール後のコマンドは `felo` です。
+
+### API キー設定
+
+推奨（永続保存）:
+
+```bash
+felo config set FELO_API_KEY your-api-key-here
+```
+
+または環境変数: `export FELO_API_KEY="your-api-key-here"`（Linux/macOS）、`$env:FELO_API_KEY="your-api-key-here"`（Windows PowerShell）。
+
+API キーは [felo.ai](https://felo.ai)（設定 → API Keys）で取得してください。
+
+### コマンド一覧
+
+| コマンド | 説明 |
+|----------|------|
+| `felo search "<query>"` | リアルタイム検索 |
+| `felo slides "<prompt>"` | PPT 生成 |
+| `felo config set FELO_API_KEY <key>` | API キー保存 |
+| `felo config get/list/path/unset` | 設定の参照/一覧/パス/削除 |
+
+---
+
+## Claude Code スキル
+
+スキルのインストール:
+
+```bash
+npx @claude/skills add felo-ai
+```
+
+`FELO_API_KEY` を設定後、「東京の今日の天気」「React 19 の新機能」などの質問で検索が自動発動します。PPT 生成は現状ターミナルの `felo slides` のみ対応です。
+
+---
+
+## リンク
+
+- [Felo オープンプラットフォーム](https://openapi.felo.ai/docs/) — API キー取得
+- [API ドキュメント](https://openapi.felo.ai/docs/api-reference/v2/chat.html)
+- [その他の例](./docs/EXAMPLES.md) | [FAQ](./docs/FAQ.md) | [GitHub Issues](https://github.com/Felo-Inc/felo-skills/issues)
+
+---
+
+**他の言語 / Other languages:** [简体中文](README.zh-CN.md) | [English](README.en.md) | [한국어](README.ko.md) | [繁體中文](README.zh-TW.md)

package/README.ko.md

@@ -0,0 +1,87 @@
+# Felo AI
+
+**무엇이든 물어보고, AI로 최신 답을 받으세요.**
+
+Felo AI는 터미널 CLI와 Claude Code 스킬을 제공하며, 한국어·영어·중국어(간체·번체)·일본어를 지원합니다.
+
+[![License](https://img.shields.io/badge/license-MIT-green)]()
+
+---
+
+## 두 가지 핵심 기능
+
+Felo AI의 핵심 기능은 **실시간 검색**과 **PPT 생성**입니다. 터미널 CLI로 사용하거나 Claude Code 스킬로 사용할 수 있으며, 검색은 자동으로 트리거됩니다.
+
+### 기능 1: 실시간 검색
+
+최신 정보를 검색하고 AI가 정리한 답변을 받습니다. 날씨, 뉴스, 가격, 문서, 기술 동향 등 「지금」 정보가 필요할 때 적합합니다.
+
+- **다국어 지원**: 원하는 언어로 질문하면 됩니다.
+- **터미널**: `felo search "질문"`
+- **Claude Code**: 스킬 설치 후 자동 트리거, 또는 `/felo-ai 질문` 입력
+- **예시**: `felo search "서울 날씨"`, `felo search "React 19 new features" --verbose`
+
+### 기능 2: PPT 생성
+
+주제나 설명을 한 문장으로 주면 PPT를 자동 생성합니다. 작업은 클라우드에서 실행되며, 완료 후 **온라인 문서 링크**를 반환해 브라우저에서 열어 확인·편집할 수 있습니다.
+
+- **터미널**: `felo slides "주제 또는 설명"`
+- **예시**: `felo slides "Felo 제품 소개, 3장"`, `felo slides "Introduction to React" --poll-timeout 300`
+
+---
+
+## 설치 및 설정
+
+### CLI 설치
+
+```bash
+npm install -g felo-ai
+```
+
+설치 없이 실행: `npx felo-ai search "서울 날씨"`  
+설치 후 사용하는 명령은 `felo` 입니다.
+
+### API 키 설정
+
+권장(영구 저장):
+
+```bash
+felo config set FELO_API_KEY your-api-key-here
+```
+
+또는 환경 변수: `export FELO_API_KEY="your-api-key-here"` (Linux/macOS), `$env:FELO_API_KEY="your-api-key-here"` (Windows PowerShell).
+
+API 키는 [felo.ai](https://felo.ai)(설정 → API Keys)에서 발급받을 수 있습니다.
+
+### 명령어 요약
+
+| 명령 | 설명 |
+|------|------|
+| `felo search "<query>"` | 실시간 검색 |
+| `felo slides "<prompt>"` | PPT 생성 |
+| `felo config set FELO_API_KEY <key>` | API 키 저장 |
+| `felo config get/list/path/unset` | 설정 조회/목록/경로/삭제 |
+
+---
+
+## Claude Code 스킬
+
+스킬 설치:
+
+```bash
+npx @claude/skills add felo-ai
+```
+
+`FELO_API_KEY` 설정 후, Claude Code에서 「서울 오늘 날씨」「React 19 새 기능」 같은 질문을 하면 검색이 자동으로 실행됩니다. PPT 생성은 현재 터미널의 `felo slides` 로만 지원됩니다.
+
+---
+
+## 링크
+
+- [Felo 오픈 플랫폼](https://openapi.felo.ai/docs/) — API 키 발급
+- [API 문서](https://openapi.felo.ai/docs/api-reference/v2/chat.html)
+- [더 많은 예시](./docs/EXAMPLES.md) | [FAQ](./docs/FAQ.md) | [GitHub Issues](https://github.com/Felo-Inc/felo-skills/issues)
+
+---
+
+**다른 언어 / Other languages:** [简体中文](README.zh-CN.md) | [English](README.en.md) | [日本語](README.ja.md) | [繁體中文](README.zh-TW.md)