npm - @tinkcarlos/skillora - Versions diffs - 0.2.1 → 0.2.3 - Mend

@tinkcarlos/skillora 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 TinkCarlos
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,69 +1,236 @@
 # Skillora
-多平台 AI 代理技能管理工具，支持 Claude Code、Cursor、Codex/GPT、Gemini、Windsurf、Aider 等平台。
+[中文文档](README.zh-CN.md)
-## 安装
+Multi-platform AI agent skill management tool, supporting Claude Code, Cursor, Codex/GPT, Gemini, Windsurf, Aider and more.
+## Features
+- **Multi-platform Support** - One skill set, multiple platforms (Claude Code, Cursor, Codex, Gemini, Windsurf, Aider)
+- **Slash Commands** - Native `/ora/<skill-name>` command support in Claude Code
+- **SKILL.md Format** - Standardized skill definition format, easy to extend and maintain
+- **Flexible Installation** - Project-level, universal, and global installation modes
+- **Zero Config** - Interactive initialization with auto-generated platform configs
+## Installation
 ```bash
 npm i -g @tinkcarlos/skillora
 ```
-> 需要 Node.js 20.6+
+> Requires Node.js 20.6+
-## 快速开始
+## Quick Start
-### 交互式初始化（推荐）
+### Interactive Initialization (Recommended)
 ```bash
 skillora init
 ```
-交互式选择平台和安装模式。
+Interactively select platforms and installation mode, auto-generates config files.
-### 非交互式初始化
+### Non-interactive Initialization
 ```bash
-# 仅 Claude Code
+# Claude Code only
 skillora init --platform claude-code
-# 多平台
+# Multiple platforms
 skillora init --platform claude-code,cursor
-# 指定安装模式
-skillora init --platform claude-code --universal  # 通用模式
-skillora init --platform claude-code --global     # 全局模式
+# Specify installation mode
+skillora init --platform claude-code --universal  # Universal mode
+skillora init --platform claude-code --global     # Global mode
+```
+## Core Skills
+Skillora includes the following core skills covering the full software development lifecycle:
+### Development
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Product Requirements** | `/ora/product-requirements` | PRD writing, user stories, acceptance criteria, competitive analysis |
+| **Fullstack Developer** | `/ora/fullstack-developer` | Frontend/backend dev, API design, database migration, skill orchestration |
+| **Bug Fixing** | `/ora/bug-fixing` | Zero-regression fixes, root cause analysis, knowledge extraction, context isolation |
+| **Code Review** | `/ora/code-review` | Layered checks, batch processing, call chain analysis, progress tracking |
+### Frontend
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Frontend Design** | `/ora/frontend-design` | 57 UI styles, 95 color palettes, responsive design, accessibility audit |
+| **React Best Practices** | `skillora read react-best-practices` | Performance optimization, state management, render optimization |
+### Backend
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **API Scaffolding** | `skillora read api-scaffolding` | FastAPI/Django/Express/NestJS templates |
+| **API Testing** | `skillora read api-testing-observability` | Contract testing, mock servers, observability |
+| **Database Migrations** | `skillora read database-migrations` | SQL migrations, version control, rollback strategies |
+### Engineering
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **CI/CD Pipeline** | `skillora read cicd-pipeline` | GitHub Actions, GitLab CI, DevSecOps |
+| **Containerization** | `skillora read containerization` | Docker, Kubernetes, Helm |
+| **Security Audit** | `skillora read security-audit` | OWASP Top 10, vulnerability scanning |
+| **Performance Optimization** | `skillora read performance-optimization` | Performance profiling, bottleneck identification |
+### Workflow
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **Brainstorming** | `skillora read brainstorming` | Socratic questioning, rapid design exploration |
+| **TDD Development** | `skillora read test-driven-development` | Test-driven development workflow |
+| **Git Worktree** | `skillora read using-git-worktrees` | Multi-branch parallel development |
+| **Verification** | `skillora read verification-before-completion` | Pre-merge checklist |
+## Usage
+### In Claude Code
+Claude Code natively supports slash commands:
+```
+/ora/bug-fixing      # Start bug fixing workflow
+/ora/code-review     # Start code review workflow
+/ora/frontend-design # Start frontend design workflow
+/ora/product-requirements # Start requirements analysis
+```
+Or use the Skill tool:
+```
+Skill("bug-fixing")
+Skill("code-review")
+```
+### Other Platforms
+Cursor, Codex, Gemini, Windsurf, Aider load skills via CLI:
+```bash
+# Read skill content (AI agent will execute automatically)
+skillora read bug-fixing
+skillora read code-review
+skillora read frontend-design
+```
+### Skill Discovery
+```bash
+# List all installed skills
+skillora list
+# List from specific directory
+skillora list --global      # Global skills
+skillora list --universal   # Universal skills
+```
+## Command Reference
+| Command | Description |
+|---------|-------------|
+| `skillora init` | Interactive project initialization |
+| `skillora install` | Install bundled skills |
+| `skillora list` | List installed skills |
+| `skillora read <name>` | Read skill content (for AI agents) |
+| `skillora sync` | Sync config to AGENTS.md |
+| `skillora remove <name>` | Remove a skill |
+### Common Options
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Operate on global skills directory (~/.claude/skills/) |
+| `-u, --universal` | Operate on universal skills directory (.agent/skills/) |
+| `-t, --target <path>` | Operate on custom directory |
+| `-f, --force` | Force overwrite existing skills |
+## Supported Platforms
+| Platform | Config Files | Invocation |
+|----------|--------------|------------|
+| Claude Code | `.claude/skills/`, `CLAUDE.md` | `/ora/<skill>` or `Skill("<skill>")` |
+| Cursor | `.cursorrules`, `AGENTS.md` | `skillora read <skill>` |
+| Codex/GPT | `AGENTS.md` (System Prompt) | `skillora read <skill>` |
+| Gemini | `AGENTS.md` (System Prompt) | `skillora read <skill>` |
+| Windsurf | `AGENTS.md` | `skillora read <skill>` |
+| Aider | `AGENTS.md` | `skillora read <skill>` |
+## Installation Modes
+| Mode | Directory | Description |
+|------|-----------|-------------|
+| Project (default) | `.claude/skills/` | Current project only |
+| Universal | `.agent/skills/` | Multi-agent compatible, project-level |
+| Global | `~/.claude/skills/` | Shared across all projects |
+## SKILL.md Format
+Each skill is a directory containing a `SKILL.md` file:
+```
+my-skill/
+├── SKILL.md           # Skill definition (required)
+├── references/        # Reference docs (optional)
+│   ├── guide.md
+│   └── patterns.md
+└── scripts/           # Helper scripts (optional)
+    └── helper.py
+```
+### SKILL.md Structure
+```markdown
+---
+name: my-skill
+description: Brief skill description
+user-invocable: true
+---
+# Skill Title
+## Trigger Conditions
+Describe when to use this skill...
+## Workflow
+1. Step one
+2. Step two
+...
+## References
+- [Guide](references/guide.md)
 ```
-## 命令参考
+### Frontmatter Fields
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Skill name (used for command invocation) |
+| `description` | string | Skill description |
+| `user-invocable` | boolean | Whether user can invoke directly (default: true) |
-| 命令 | 说明 |
-|------|------|
-| `skillora init` | 交互式初始化项目 |
-| `skillora install` | 安装内置技能 |
-| `skillora list` | 列出已安装技能 |
-| `skillora read <name>` | 读取技能内容（给 AI agent 用） |
-| `skillora sync` | 同步配置到 AGENTS.md |
-| `skillora remove <name>` | 删除技能 |
+## Skill Development
-## 支持的平台
+### Creating a New Skill
-| 平台 | 配置文件 |
-|------|----------|
-| Claude Code | `.claude/skills/`, `CLAUDE.md` |
-| Cursor | `.cursorrules`, `AGENTS.md` |
-| Codex/GPT | `AGENTS.md` (System Prompt) |
-| Gemini | `AGENTS.md` (System Prompt) |
-| Windsurf | `AGENTS.md` |
-| Aider | `AGENTS.md` |
+1. Create skill directory under `.claude/skills/`
+2. Write `SKILL.md` file
+3. Run `skillora sync` to update AGENTS.md
-## 安装模式
+### Best Practices
-| 模式 | 目录 | 说明 |
-|------|------|------|
-| 项目模式（默认） | `.claude/skills/` | 仅当前项目 |
-| 通用模式 | `.agent/skills/` | 多代理兼容 |
-| 全局模式 | `~/.claude/skills/` | 所有项目共享 |
+- **Single Responsibility** - Each skill focuses on one domain
+- **Clear Triggers** - Clearly describe when to use the skill
+- **Structured Workflow** - Provide clear step-by-step guidance
+- **Separate References** - Put detailed content in references/ directory
-## 许可证
+## License
-UNLICENSED
+[MIT](LICENSE)

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,236 @@
+# Skillora
+[English](README.md)
+多平台 AI 代理技能管理工具，支持 Claude Code、Cursor、Codex/GPT、Gemini、Windsurf、Aider 等平台。
+## 特点
+- **多平台支持** - 一套技能，多平台使用（Claude Code、Cursor、Codex、Gemini、Windsurf、Aider）
+- **斜杠命令** - Claude Code 原生支持 `/ora/<skill-name>` 命令调用
+- **SKILL.md 格式** - 标准化的技能定义格式，易于扩展和维护
+- **灵活安装** - 支持项目级、通用级、全局级三种安装模式
+- **零配置** - 交互式初始化，自动生成平台配置文件
+## 安装
+```bash
+npm i -g @tinkcarlos/skillora
+```
+> 需要 Node.js 20.6+
+## 快速开始
+### 交互式初始化（推荐）
+```bash
+skillora init
+```
+交互式选择平台和安装模式，自动生成配置文件。
+### 非交互式初始化
+```bash
+# 仅 Claude Code
+skillora init --platform claude-code
+# 多平台
+skillora init --platform claude-code,cursor
+# 指定安装模式
+skillora init --platform claude-code --universal  # 通用模式
+skillora init --platform claude-code --global     # 全局模式
+```
+## 核心技能
+Skillora 内置以下核心技能，覆盖软件开发全流程：
+### 开发类
+| 技能 | 命令 | 说明 |
+|------|------|------|
+| **需求分析** | `/ora/product-requirements` | PRD 编写、用户故事、验收标准、竞品分析 |
+| **全栈开发** | `/ora/fullstack-developer` | 前后端开发、API 设计、数据库迁移、技能编排 |
+| **Bug 修复** | `/ora/bug-fixing` | 零回归修复、根因分析、知识提取、上下文隔离 |
+| **代码审查** | `/ora/code-review` | 分层检查、批量处理、调用链分析、进度追踪 |
+### 前端类
+| 技能 | 命令 | 说明 |
+|------|------|------|
+| **前端设计** | `/ora/frontend-design` | 57 种 UI 风格、95 种配色、响应式设计、无障碍审查 |
+| **React 最佳实践** | `skillora read react-best-practices` | 性能优化、状态管理、渲染优化 |
+### 后端类
+| 技能 | 命令 | 说明 |
+|------|------|------|
+| **API 脚手架** | `skillora read api-scaffolding` | FastAPI/Django/Express/NestJS 模板 |
+| **API 测试** | `skillora read api-testing-observability` | 契约测试、Mock 服务、可观测性 |
+| **数据库迁移** | `skillora read database-migrations` | SQL 迁移、版本控制、回滚策略 |
+### 工程类
+| 技能 | 命令 | 说明 |
+|------|------|------|
+| **CI/CD 流水线** | `skillora read cicd-pipeline` | GitHub Actions、GitLab CI、DevSecOps |
+| **容器化** | `skillora read containerization` | Docker、Kubernetes、Helm |
+| **安全审计** | `skillora read security-audit` | OWASP Top 10、漏洞扫描 |
+| **性能优化** | `skillora read performance-optimization` | 性能分析、瓶颈定位 |
+### 流程类
+| 技能 | 命令 | 说明 |
+|------|------|------|
+| **头脑风暴** | `skillora read brainstorming` | 苏格拉底式提问、快速设计探索 |
+| **TDD 开发** | `skillora read test-driven-development` | 测试驱动开发流程 |
+| **Git Worktree** | `skillora read using-git-worktrees` | 多分支并行开发 |
+| **完成验证** | `skillora read verification-before-completion` | 合并前检查清单 |
+## 使用说明
+### Claude Code 中使用
+Claude Code 原生支持斜杠命令调用技能：
+```
+/ora/bug-fixing      # 启动 Bug 修复流程
+/ora/code-review     # 启动代码审查流程
+/ora/frontend-design # 启动前端设计流程
+/ora/product-requirements # 启动需求分析流程
+```
+也可以使用 Skill 工具：
+```
+Skill("bug-fixing")
+Skill("code-review")
+```
+### 其他平台使用
+Cursor、Codex、Gemini、Windsurf、Aider 等平台通过 CLI 命令加载技能：
+```bash
+# 读取技能内容（AI agent 会自动执行）
+skillora read bug-fixing
+skillora read code-review
+skillora read frontend-design
+```
+### 技能搜索
+```bash
+# 列出所有已安装技能
+skillora list
+# 从特定目录列出
+skillora list --global      # 全局技能
+skillora list --universal   # 通用技能
+```
+## 命令参考
+| 命令 | 说明 |
+|------|------|
+| `skillora init` | 交互式初始化项目 |
+| `skillora install` | 安装内置技能 |
+| `skillora list` | 列出已安装技能 |
+| `skillora read <name>` | 读取技能内容（给 AI agent 用） |
+| `skillora sync` | 同步配置到 AGENTS.md |
+| `skillora remove <name>` | 删除技能 |
+### 通用选项
+| 选项 | 说明 |
+|------|------|
+| `-g, --global` | 操作全局技能目录 (~/.claude/skills/) |
+| `-u, --universal` | 操作通用技能目录 (.agent/skills/) |
+| `-t, --target <path>` | 操作自定义目录 |
+| `-f, --force` | 强制覆盖已存在的技能 |
+## 支持的平台
+| 平台 | 配置文件 | 调用方式 |
+|------|----------|----------|
+| Claude Code | `.claude/skills/`, `CLAUDE.md` | `/ora/<skill>` 或 `Skill("<skill>")` |
+| Cursor | `.cursorrules`, `AGENTS.md` | `skillora read <skill>` |
+| Codex/GPT | `AGENTS.md` (System Prompt) | `skillora read <skill>` |
+| Gemini | `AGENTS.md` (System Prompt) | `skillora read <skill>` |
+| Windsurf | `AGENTS.md` | `skillora read <skill>` |
+| Aider | `AGENTS.md` | `skillora read <skill>` |
+## 安装模式
+| 模式 | 目录 | 说明 |
+|------|------|------|
+| 项目模式（默认） | `.claude/skills/` | 仅当前项目可用 |
+| 通用模式 | `.agent/skills/` | 多代理兼容，项目级 |
+| 全局模式 | `~/.claude/skills/` | 所有项目共享 |
+## SKILL.md 格式规范
+每个技能由一个目录组成，必须包含 `SKILL.md` 文件：
+```
+my-skill/
+├── SKILL.md           # 技能定义（必需）
+├── references/        # 参考文档（可选）
+│   ├── guide.md
+│   └── patterns.md
+└── scripts/           # 辅助脚本（可选）
+    └── helper.py
+```
+### SKILL.md 结构
+```markdown
+---
+name: my-skill
+description: 技能的简短描述
+user-invocable: true
+---
+# 技能标题
+## 触发条件
+描述何时应该使用此技能...
+## 工作流程
+1. 步骤一
+2. 步骤二
+...
+## 参考文档
+- [指南](references/guide.md)
+```
+### Frontmatter 字段
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 技能名称（用于命令调用） |
+| `description` | string | 技能描述 |
+| `user-invocable` | boolean | 是否支持用户直接调用（默认 true） |
+## 技能开发
+### 创建新技能
+1. 在 `.claude/skills/` 下创建技能目录
+2. 编写 `SKILL.md` 文件
+3. 运行 `skillora sync` 更新 AGENTS.md
+### 技能最佳实践
+- **单一职责** - 每个技能专注一个领域
+- **清晰触发** - 明确描述何时使用此技能
+- **结构化流程** - 提供清晰的步骤指引
+- **参考分离** - 详细内容放在 references/ 目录
+## 许可证
+[MIT](LICENSE)

package/lib/init.js CHANGED Viewed

@@ -97,14 +97,23 @@ function listSkillDirs(rootDir) {
     .filter((d) => fs.existsSync(path.join(d, "SKILL.md")));
 }
-function generateClaudeMd(skillCount) {
+function generateClaudeMd(skills) {
+  const invocableSkills = skills.filter((s) => s.userInvocable);
+  const slashCommands = invocableSkills.map((s) => `/ora/${s.name}`).join(", ");
   return `# CLAUDE.md
 ## Skills System
-本项目已安装 ${skillCount} 个技能，使用 \`skillora read <name>\` 加载。
+本项目已安装 ${skills.length} 个技能。
-运行 \`skillora list\` 查看所有可用技能。
+### 斜杠命令（推荐）
+${slashCommands || "(无可调用技能)"}
+### CLI 命令
+\`skillora read <name>\` 加载技能详情
+\`skillora list\` 查看所有可用技能
 `;
 }
@@ -125,6 +134,8 @@ ${skillList}
 }
 function generateAgentsMd(skills, cliName) {
+  const invocableSkills = skills.filter((s) => s.userInvocable);
+  const slashCommands = invocableSkills.map((s) => `/ora/${s.name}`).join(", ");
   const skillTable = skills
     .map((s) => `| ${s.name} | ${s.description} |`)
     .join("\n");
@@ -142,7 +153,8 @@ ${skillTable}
 ### Claude Code
 - 原生支持 \`.claude/skills/\` 目录
-- 使用 \`Skill("name")\` 调用
+- 斜杠命令: ${slashCommands || "(无)"}
+- 或使用 \`Skill("name")\` 调用
 ### Cursor
 - 使用 \`.cursorrules\` 配置
@@ -292,8 +304,8 @@ async function runInit(options, bundledSkillsDir) {
   // 生成平台配置文件
   if (platforms.includes("claude-code")) {
     const claudeMdPath = path.join(cwd, "CLAUDE.md");
-    if (!fs.existsSync(claudeMdPath)) {
-      fs.writeFileSync(claudeMdPath, generateClaudeMd(skills.length), "utf8");
+    if (!fs.existsSync(claudeMdPath) || options.force) {
+      fs.writeFileSync(claudeMdPath, generateClaudeMd(skills), "utf8");
       created.push("CLAUDE.md");
     }
   }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tinkcarlos/skillora",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "CLI installer for bundled Claude Code skills (SKILL.md format)",
   "bin": {
     "skillora": "bin/cli.js"
@@ -19,7 +19,7 @@
     "agents",
     "openskills"
   ],
-  "license": "UNLICENSED",
+  "license": "MIT",
   "engines": {
     "node": ">=20.6.0"
   },