Agent Skills 深度指南

my-skill/
├── SKILL.md                    # 必需：指令 + 元数据（frontmatter）
├── agents/
│   └── openai.yaml             # 推荐：UI 元数据、策略、MCP 依赖声明
├── scripts/                    # 可选：可执行脚本
│   ├── setup.sh
│   ├── validate.py
│   └── cleanup.sh
├── references/                 # 可选：参考文档
│   ├── api-guide.md
│   ├── architecture.md
│   └── examples.md
├── assets/                     # 可选：模板、资源文件
│   └── template.yaml
└── LICENSE.txt                 # 推荐：许可证

---
name: spring-boot-service
description: >
  Create and scaffold Spring Boot 3.x microservice modules for Refinex-Cloud.
  Use when the user asks to create a new service, add a new module, or scaffold
  a Spring Boot project. Do NOT use for frontend tasks or non-Java projects.
---
​
# Spring Boot Service Scaffolding
​
## 前置检查
1. 确认项目根目录存在 `pom.xml`（Maven 多模块项目）
2. 确认 Java 版本 ≥ 21
​
## 工作流
1. 从模板生成模块目录结构
2. 配置 `pom.xml` 继承父工程
3. 生成标准化的 Application 启动类
4. 生成 bootstrap.yml + application.yml
5. 添加到父工程 modules 列表
​
## 参考资料
- 模块结构规范：见 `references/module-structure.md`
- POM 配置模板：见 `references/pom-template.md`

# agents/openai.yaml — 完整字段参考
​
# === UI 元数据（Codex App 中展示） ===
interface:
  display_name: "Spring Boot Service"                # 用户可见的展示名
  short_description: "Scaffold Spring Boot modules"  # 简短描述
  icon_small: "./assets/spring-small.svg"            # 小图标
  icon_large: "./assets/spring-large.png"            # 大图标
  brand_color: "#6DB33F"                             # 品牌色（十六进制）
  default_prompt: "创建一个新的 Spring Boot 微服务模块"  # 默认提示语
​
# === 触发策略 ===
policy:
  allow_implicit_invocation: true  # 默认 true，设为 false 则只能显式 $skill 调用
​
# === MCP 依赖声明 ===
dependencies:
  tools:
    - type: "mcp"
      value: "github"                        # 对应 config.toml 中的 mcp_servers 名称
      description: "GitHub MCP server"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"

#!/usr/bin/env python3
"""validate_module.py — 验证 Spring Boot 模块结构是否规范"""
import json
import sys
from pathlib import Path
​
def validate(module_path: str) -> dict:
    path = Path(module_path)
    errors = []
    # 检查 pom.xml
    if not (path / "pom.xml").exists():
        errors.append("Missing pom.xml")
    # 检查 Application 启动类
    src_main = path / "src" / "main" / "java"
    if not src_main.exists():
        errors.append("Missing src/main/java directory")
    return {"valid": len(errors) == 0, "errors": errors}
​
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "Usage: validate_module.py <module_path>"}), file=sys.stderr)
        sys.exit(1)
    result = validate(sys.argv[1])
    print(json.dumps(result))  # stdout: 结构化输出
    sys.exit(0 if result["valid"] else 1)

references/
├── module-structure.md          # 模块目录结构规范
├── pom-template.md              # POM 配置模板
├── nacos-config.md              # Nacos 配置规范
├── security-conventions.md      # 安全编码约定
└── api-design-guide.md          # API 设计规范

$spring-boot-service     # 显式调用自定义 Skill
$gh-fix-ci               # 显式调用修复 CI Skill
$security-best-practices # 显式调用安全审查 Skill

$skill-creator

# 1. 创建目录结构
mkdir -p .agents/skills/spring-boot-service/{agents,scripts,references,assets}
​
# 2. 编写 SKILL.md
cat > .agents/skills/spring-boot-service/SKILL.md << 'EOF'
---
name: spring-boot-service
description: >
  Create and scaffold Spring Boot 3.x microservice modules for Refinex-Cloud.
  Use when the user asks to create a new service, add a new module, or scaffold
  a Spring Boot project. Do NOT use for frontend tasks or non-Java projects.
---
​
# Spring Boot Service Scaffolding
​
## 工作流
1. ...
EOF
​
# 3.（可选）编写 agents/openai.yaml
# 4.（可选）添加 scripts/ 和 references/
# 5. 重启 Codex 或等待自动检测

# agents/openai.yaml
dependencies:
  tools:
    - type: "mcp"
      value: "github"                        # config.toml 中的 mcp_servers 名称
      description: "GitHub MCP for PR and Issue management"
      transport: "streamable_http"
      url: "https://api.githubcopilot.com/mcp/"
    - type: "mcp"
      value: "context7"
      description: "Context7 for up-to-date docs"
      transport: "stdio"

---
name: gh-release
description: >
  Create a GitHub release with changelog. Use when the user asks to
  release, tag, or publish a new version. Do NOT use for pre-release or snapshot.
---
​
# GitHub Release Workflow
​
## 前置条件
- GitHub MCP 已配置且已 OAuth 登录
- 当前分支为 main/master
​
## 工作流
1. 运行 `git log` 获取自上次 tag 以来的 commit 列表
2. 按 Conventional Commits 分类生成 CHANGELOG
3. 使用 GitHub MCP 的 `create_release` 工具创建 Release
4. 使用 GitHub MCP 的 `create_pull_request` 工具提交 CHANGELOG 更新 PR

# 在 PR 评论中
@codex 使用 $gh-fix-ci 修复这个 CI 失败

# 在 PR 评论中
@codex 使用 $security-best-practices 审查这个 PR 的安全性

# 1. 从 openai/skills 安装 Curated Skill（按名称）
$skill-installer gh-fix-ci
​
# 2. 从 openai/skills 安装 Experimental Skill（指定路径）
$skill-installer install the create-plan skill from the .experimental folder
​
# 3. 从 GitHub URL 安装
$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan
​
# 4. 手动安装（复制目录）
cp -r /path/to/my-skill ~/.agents/skills/

# 查看已安装的 Skills
/skills                              # TUI 内
​
# 禁用 Skill（不删除）
# 在 ~/.codex/config.toml 中：
# [[skills.config]]
# path = "/path/to/skill/SKILL.md"
# enabled = false
​
# 删除 Skill
rm -rf ~/.codex/skills/<skill-name>  # 或对应目录

$skill-installer gh-fix-ci

$skill-installer gh-address-comments

$skill-installer frontend-skill

$skill-installer playwright

$skill-installer security-best-practices

$skill-installer screenshot

.agents/skills/spring-boot-service/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── validate_module.py
├── references/
│   ├── module-structure.md
│   ├── pom-template.md
│   └── nacos-config.md
└── assets/
    ├── Application.java.template
    └── bootstrap.yml.template

---
name: spring-boot-service
description: >
  Create and scaffold a new Spring Boot 3.x microservice module for Refinex-Cloud
  (Maven multi-module project with Spring Cloud Alibaba). Use when the user asks
  to create a new service, add a new module, or scaffold a Spring Boot project
  within the Refinex-Cloud monorepo. Do NOT use for frontend tasks, non-Java
  projects, or modifications to existing modules.
---
​
# Spring Boot Service Scaffolding
​
## 前置检查
1. 确认当前目录为 Refinex-Cloud 项目根（存在根 `pom.xml` 且 `<groupId>` 为 `com.refinex`）
2. 确认 Java 版本 ≥ 21（`java -version`）
3. 确认 Maven 可用（`mvn -version`）
​
## 工作流
​
### Step 1: 收集信息
- 模块名称（如 `refinex-notification`）
- 模块描述
- 需要的核心依赖（从已有模块参考）
​
### Step 2: 创建模块目录
按照 `references/module-structure.md` 中的标准结构创建目录：
refinex-<name>/
├── pom.xml
└── src/
├── main/
│   ├── java/com/refinex/<name>/
│   │   ├── <Name>[Application.java](http://Application.java
│   │   ├── controller/
│   │   ├── service/
│   │   ├── mapper/
│   │   ├── domain/
│   │   └── config/
│   └── resources/
│       ├── bootstrap.yml
│       └── application.yml
└── test/
└── java/com/refinex/<name>/
​
### Step 3: 配置 POM
参考 `references/pom-template.md`，生成 `pom.xml`：
- 继承父工程 `refinex-cloud` 的 `<parent>`
- 添加 `spring-boot-starter-web`、`spring-cloud-starter-alibaba-nacos-discovery` 等基础依赖
- 添加 `refinex-common-core`、`refinex-common-security` 等通用模块依赖
​
### Step 4: 生成启动类
使用 `assets/Application.java.template` 生成 Application 启动类，包含：
- `@SpringBootApplication`
- `@EnableDiscoveryClient`
- 标准化的启动日志
​
### Step 5: 生成配置文件
参考 `references/nacos-config.md`，生成 `bootstrap.yml`：
- 配置 Nacos 服务发现地址
- 配置应用名、端口、Profile
​
### Step 6: 注册到父工程
在根 `pom.xml` 的 `<modules>` 列表中添加新模块。
​
### Step 7: 验证
运行 `scripts/validate_module.py <module-path>` 验证模块结构完整性。
然后执行 `mvn clean compile -pl refinex-<name>` 确认编译通过。
​
## 约定
- 包名统一使用 `com.refinex.<module-name>`
- 端口分配参考已有服务的端口段
- 所有模块必须接入 Nacos 服务发现
- 启动类命名：`<ModuleName>Application.java`

interface:
  display_name: "Spring Boot Service"
  short_description: "Scaffold Refinex-Cloud microservice modules"
  brand_color: "#6DB33F"
  default_prompt: "为 Refinex-Cloud 创建一个新的微服务模块"
​
policy:
  allow_implicit_invocation: true
​
dependencies:
  tools:
    - type: "mcp"
      value: "context7"
      description: "Context7 for Spring Boot documentation"
      transport: "stdio"

#!/usr/bin/env python3
"""validate_module.py — 验证 Spring Boot 模块结构是否符合 Refinex-Cloud 规范"""
import json
import sys
from pathlib import Path
​
def validate(module_path: str) -> dict:
    path = Path(module_path)
    errors = []
    warnings = []
​
    # 必须文件检查
    required_files = [
        "pom.xml",
        "src/main/resources/bootstrap.yml",
    ]
    for f in required_files:
        if not (path / f).exists():
            errors.append(f"Missing required file: {f}")
​
    # 必须目录检查
    required_dirs = [
        "src/main/java",
        "src/main/resources",
        "src/test/java",
    ]
    for d in required_dirs:
        if not (path / d).is_dir():
            errors.append(f"Missing required directory: {d}")
​
    # Application 启动类检查
    java_files = list((path / "src" / "main" / "java").rglob("*Application.java"))
    if not java_files:
        errors.append("Missing Application.java entry point")
    elif len(java_files) > 1:
        warnings.append(f"Multiple Application classes found: {[str(f) for f in java_files]}")
​
    return {
        "valid": len(errors) == 0,
        "errors": errors,
        "warnings": warnings,
        "module": path.name,
    }
​
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "Usage: validate_module.py <module_path>"}), file=sys.stderr)
        sys.exit(1)
    result = validate(sys.argv[1])
    print(json.dumps(result, indent=2))
    sys.exit(0 if result["valid"] else 1)

# Refinex-Cloud 模块标准目录结构
​
refinex-<name>/
├── pom.xml                          # 模块 POM，继承 refinex-cloud 父工程
└── src/
    ├── main/
    │   ├── java/com/refinex/<name>/
    │   │   ├── <Name>Application.java   # 启动类
    │   │   ├── controller/              # REST 控制器
    │   │   ├── service/                 # 业务逻辑层
    │   │   │   └── impl/
    │   │   ├── mapper/                  # MyBatis Mapper
    │   │   ├── domain/                  # 实体类
    │   │   │   ├── entity/
    │   │   │   ├── dto/
    │   │   │   └── vo/
    │   │   └── config/                  # 配置类
    │   └── resources/
    │       ├── bootstrap.yml            # Nacos 引导配置
    │       ├── application.yml          # 应用配置
    │       └── mapper/                  # MyBatis XML
    └── test/
        └── java/com/refinex/<name>/
​
## 命名约定
- 模块名：`refinex-` 前缀 + 功能名（kebab-case）
- 包名：`com.refinex.<name>`（点分隔，小写）
- 启动类：`<Name>Application`（PascalCase）
- 端口：参考端口分配表，避免冲突

# === 推荐安装的 6 个 Curated Skills ===
​
# 1. 修复 GitHub Actions CI 失败
$skill-installer gh-fix-ci
​
# 2. 处理 PR Review 评论
$skill-installer gh-address-comments
​
# 3. 高质量前端 UI 开发
$skill-installer frontend-skill
​
# 4. Playwright 浏览器 CLI 自动化
$skill-installer playwright
​
# 5. 安全最佳实践审查
$skill-installer security-best-practices
​
# 6. 桌面截图
$skill-installer screenshot