From 83f6d5679c11d6e8074ffb74fd55e086179f6a3b Mon Sep 17 00:00:00 2001 From: Jinyi_Yang <107851451+YannJY02@users.noreply.github.com> Date: Fri, 13 Mar 2026 07:40:02 +0100 Subject: [PATCH] feat(skills): add prompt-optimizer skill and /prompt-optimize command (#418) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(skills): add prompt-optimizer skill and /prompt-optimize command Adds a prompt-optimizer skill that analyzes draft prompts, matches them to ECC components (skills/commands/agents), and outputs a ready-to-paste optimized prompt. Advisory role only — never executes the task. Features: - 6-phase analysis pipeline (project detection, intent, scope, component matching, missing context, workflow + model recommendation) - Auto-detects project tech stack from package.json, go.mod, etc. - Maps intents to ECC commands, skills, and agents by type and tech stack - Recommends correct model tier (Sonnet vs Opus) based on task complexity - Outputs Full + Quick versions of the optimized prompt - Hard gate: never executes the task, only produces advisory output - AskUserQuestion trigger when 3+ critical context items are missing - Multi-prompt splitting guidance for HIGH/EPIC scope tasks - Feedback footer for iterative refinement Also adds /prompt-optimize command as an explicit invocation entry point. * fix: keep prompt optimizer advisory-only * fix: refine prompt optimizer guidance --------- Co-authored-by: Affaan Mustafa --- commands/prompt-optimize.md | 38 +++ skills/prompt-optimizer/SKILL.md | 397 +++++++++++++++++++++++++++++++ 2 files changed, 435 insertions(+) create mode 100644 commands/prompt-optimize.md create mode 100644 skills/prompt-optimizer/SKILL.md diff --git a/commands/prompt-optimize.md b/commands/prompt-optimize.md new file mode 100644 index 00000000..b067fe45 --- /dev/null +++ b/commands/prompt-optimize.md @@ -0,0 +1,38 @@ +--- +description: Analyze a draft prompt and output an optimized, ECC-enriched version ready to paste and run. Does NOT execute the task — outputs advisory analysis only. +--- + +# /prompt-optimize + +Analyze and optimize the following prompt for maximum ECC leverage. + +## Your Task + +Apply the **prompt-optimizer** skill to the user's input below. Follow the 6-phase analysis pipeline: + +0. **Project Detection** — Read CLAUDE.md, detect tech stack from project files (package.json, go.mod, pyproject.toml, etc.) +1. **Intent Detection** — Classify the task type (new feature, bug fix, refactor, research, testing, review, documentation, infrastructure, design) +2. **Scope Assessment** — Evaluate complexity (TRIVIAL / LOW / MEDIUM / HIGH / EPIC), using codebase size as signal if detected +3. **ECC Component Matching** — Map to specific skills, commands, agents, and model tier +4. **Missing Context Detection** — Identify gaps. If 3+ critical items missing, ask the user to clarify before generating +5. **Workflow & Model** — Determine lifecycle position, recommend model tier, and split into multiple prompts if HIGH/EPIC + +## Output Requirements + +- Present diagnosis, recommended ECC components, and an optimized prompt using the Output Format from the prompt-optimizer skill +- Provide both **Full Version** (detailed) and **Quick Version** (compact, varied by intent type) +- Respond in the same language as the user's input +- The optimized prompt must be complete and ready to copy-paste into a new session +- End with a footer offering adjustment or a clear next step for starting a separate execution request + +## CRITICAL + +Do NOT execute the user's task. Output ONLY the analysis and optimized prompt. +If the user asks for direct execution, explain that `/prompt-optimize` only produces advisory output and tell them to start a normal task request instead. + +Note: `blueprint` is a **skill**, not a slash command. Write "Use the blueprint skill" +instead of presenting it as a `/...` command. + +## User Input + +$ARGUMENTS diff --git a/skills/prompt-optimizer/SKILL.md b/skills/prompt-optimizer/SKILL.md new file mode 100644 index 00000000..3241968c --- /dev/null +++ b/skills/prompt-optimizer/SKILL.md @@ -0,0 +1,397 @@ +--- +name: prompt-optimizer +description: >- + Analyze raw prompts, identify intent and gaps, match ECC components + (skills/commands/agents/hooks), and output a ready-to-paste optimized + prompt. Advisory role only — never executes the task itself. + TRIGGER when: user says "optimize prompt", "improve my prompt", + "how to write a prompt for", "help me prompt", "rewrite this prompt", + or explicitly asks to enhance prompt quality. Also triggers on Chinese + equivalents: "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令". + DO NOT TRIGGER when: user wants the task executed directly, or says + "just do it" / "直接做". DO NOT TRIGGER when user says "优化代码", + "优化性能", "optimize performance", "optimize this code" — those are + refactoring/performance tasks, not prompt optimization. +origin: community +metadata: + author: YannJY02 + version: "1.0.0" +--- + +# Prompt Optimizer + +Analyze a draft prompt, critique it, match it to ECC ecosystem components, +and output a complete optimized prompt the user can paste and run. + +## When to Use + +- User says "optimize this prompt", "improve my prompt", "rewrite this prompt" +- User says "help me write a better prompt for..." +- User says "what's the best way to ask Claude Code to..." +- User says "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令" +- User pastes a draft prompt and asks for feedback or enhancement +- User says "I don't know how to prompt for this" +- User says "how should I use ECC for..." +- User explicitly invokes `/prompt-optimize` + +### Do Not Use When + +- User wants the task done directly (just execute it) +- User says "优化代码", "优化性能", "optimize this code", "optimize performance" — these are refactoring tasks, not prompt optimization +- User is asking about ECC configuration (use `configure-ecc` instead) +- User wants a skill inventory (use `skill-stocktake` instead) +- User says "just do it" or "直接做" + +## How It Works + +**Advisory only — do not execute the user's task.** + +Do NOT write code, create files, run commands, or take any implementation +action. Your ONLY output is an analysis plus an optimized prompt. + +If the user says "just do it", "直接做", or "don't optimize, just execute", +do not switch into implementation mode inside this skill. Tell the user this +skill only produces optimized prompts, and instruct them to make a normal +task request if they want execution instead. + +Run this 6-phase pipeline sequentially. Present results using the Output Format below. + +### Analysis Pipeline + +### Phase 0: Project Detection + +Before analyzing the prompt, detect the current project context: + +1. Check if a `CLAUDE.md` exists in the working directory — read it for project conventions +2. Detect tech stack from project files: + - `package.json` → Node.js / TypeScript / React / Next.js + - `go.mod` → Go + - `pyproject.toml` / `requirements.txt` → Python + - `Cargo.toml` → Rust + - `build.gradle` / `pom.xml` → Java / Kotlin / Spring Boot + - `Package.swift` → Swift + - `Gemfile` → Ruby + - `composer.json` → PHP + - `*.csproj` / `*.sln` → .NET + - `Makefile` / `CMakeLists.txt` → C / C++ + - `cpanfile` / `Makefile.PL` → Perl +3. Note detected tech stack for use in Phase 3 and Phase 4 + +If no project files are found (e.g., the prompt is abstract or for a new project), +skip detection and flag "tech stack unknown" in Phase 4. + +### Phase 1: Intent Detection + +Classify the user's task into one or more categories: + +| Category | Signal Words | Example | +|----------|-------------|---------| +| New Feature | build, create, add, implement, 创建, 实现, 添加 | "Build a login page" | +| Bug Fix | fix, broken, not working, error, 修复, 报错 | "Fix the auth flow" | +| Refactor | refactor, clean up, restructure, 重构, 整理 | "Refactor the API layer" | +| Research | how to, what is, explore, investigate, 怎么, 如何 | "How to add SSO" | +| Testing | test, coverage, verify, 测试, 覆盖率 | "Add tests for the cart" | +| Review | review, audit, check, 审查, 检查 | "Review my PR" | +| Documentation | document, update docs, 文档 | "Update the API docs" | +| Infrastructure | deploy, CI, docker, database, 部署, 数据库 | "Set up CI/CD pipeline" | +| Design | design, architecture, plan, 设计, 架构 | "Design the data model" | + +### Phase 2: Scope Assessment + +If Phase 0 detected a project, use codebase size as a signal. Otherwise, estimate +from the prompt description alone and mark the estimate as uncertain. + +| Scope | Heuristic | Orchestration | +|-------|-----------|---------------| +| TRIVIAL | Single file, < 50 lines | Direct execution | +| LOW | Single component or module | Single command or skill | +| MEDIUM | Multiple components, same domain | Command chain + /verify | +| HIGH | Cross-domain, 5+ files | /plan first, then phased execution | +| EPIC | Multi-session, multi-PR, architectural shift | Use blueprint skill for multi-session plan | + +### Phase 3: ECC Component Matching + +Map intent + scope + tech stack (from Phase 0) to specific ECC components. + +#### By Intent Type + +| Intent | Commands | Skills | Agents | +|--------|----------|--------|--------| +| New Feature | /plan, /tdd, /code-review, /verify | tdd-workflow, verification-loop | planner, tdd-guide, code-reviewer | +| Bug Fix | /tdd, /build-fix, /verify | tdd-workflow | tdd-guide, build-error-resolver | +| Refactor | /refactor-clean, /code-review, /verify | verification-loop | refactor-cleaner, code-reviewer | +| Research | /plan | search-first, iterative-retrieval | — | +| Testing | /tdd, /e2e, /test-coverage | tdd-workflow, e2e-testing | tdd-guide, e2e-runner | +| Review | /code-review | security-review | code-reviewer, security-reviewer | +| Documentation | /update-docs, /update-codemaps | — | doc-updater | +| Infrastructure | /plan, /verify | docker-patterns, deployment-patterns, database-migrations | architect | +| Design (MEDIUM-HIGH) | /plan | — | planner, architect | +| Design (EPIC) | — | blueprint (invoke as skill) | planner, architect | + +#### By Tech Stack + +| Tech Stack | Skills to Add | Agent | +|------------|--------------|-------| +| Python / Django | django-patterns, django-tdd, django-security, django-verification, python-patterns, python-testing | python-reviewer | +| Go | golang-patterns, golang-testing | go-reviewer, go-build-resolver | +| Spring Boot / Java | springboot-patterns, springboot-tdd, springboot-security, springboot-verification, java-coding-standards, jpa-patterns | code-reviewer | +| Kotlin / Android | kotlin-coroutines-flows, compose-multiplatform-patterns, android-clean-architecture | kotlin-reviewer | +| TypeScript / React | frontend-patterns, backend-patterns, coding-standards | code-reviewer | +| Swift / iOS | swiftui-patterns, swift-concurrency-6-2, swift-actor-persistence, swift-protocol-di-testing | code-reviewer | +| PostgreSQL | postgres-patterns, database-migrations | database-reviewer | +| Perl | perl-patterns, perl-testing, perl-security | code-reviewer | +| C++ | cpp-coding-standards, cpp-testing | code-reviewer | +| Other / Unlisted | coding-standards (universal) | code-reviewer | + +### Phase 4: Missing Context Detection + +Scan the prompt for missing critical information. Check each item and mark +whether Phase 0 auto-detected it or the user must supply it: + +- [ ] **Tech stack** — Detected in Phase 0, or must user specify? +- [ ] **Target scope** — Files, directories, or modules mentioned? +- [ ] **Acceptance criteria** — How to know the task is done? +- [ ] **Error handling** — Edge cases and failure modes addressed? +- [ ] **Security requirements** — Auth, input validation, secrets? +- [ ] **Testing expectations** — Unit, integration, E2E? +- [ ] **Performance constraints** — Load, latency, resource limits? +- [ ] **UI/UX requirements** — Design specs, responsive, a11y? (if frontend) +- [ ] **Database changes** — Schema, migrations, indexes? (if data layer) +- [ ] **Existing patterns** — Reference files or conventions to follow? +- [ ] **Scope boundaries** — What NOT to do? + +**If 3+ critical items are missing**, ask the user up to 3 clarification +questions before generating the optimized prompt. Then incorporate the +answers into the optimized prompt. + +### Phase 5: Workflow & Model Recommendation + +Determine where this prompt sits in the development lifecycle: + +``` +Research → Plan → Implement (TDD) → Review → Verify → Commit +``` + +For MEDIUM+ tasks, always start with /plan. For EPIC tasks, use blueprint skill. + +**Model recommendation** (include in output): + +| Scope | Recommended Model | Rationale | +|-------|------------------|-----------| +| TRIVIAL-LOW | Sonnet 4.6 | Fast, cost-efficient for simple tasks | +| MEDIUM | Sonnet 4.6 | Best coding model for standard work | +| HIGH | Sonnet 4.6 (main) + Opus 4.6 (planning) | Opus for architecture, Sonnet for implementation | +| EPIC | Opus 4.6 (blueprint) + Sonnet 4.6 (execution) | Deep reasoning for multi-session planning | + +**Multi-prompt splitting** (for HIGH/EPIC scope): + +For tasks that exceed a single session, split into sequential prompts: +- Prompt 1: Research + Plan (use search-first skill, then /plan) +- Prompt 2-N: Implement one phase per prompt (each ends with /verify) +- Final Prompt: Integration test + /code-review across all phases +- Use /save-session and /resume-session to preserve context between sessions + +--- + +## Output Format + +Present your analysis in this exact structure. Respond in the same language +as the user's input. + +### Section 1: Prompt Diagnosis + +**Strengths:** List what the original prompt does well. + +**Issues:** + +| Issue | Impact | Suggested Fix | +|-------|--------|---------------| +| (problem) | (consequence) | (how to fix) | + +**Needs Clarification:** Numbered list of questions the user should answer. +If Phase 0 auto-detected the answer, state it instead of asking. + +### Section 2: Recommended ECC Components + +| Type | Component | Purpose | +|------|-----------|---------| +| Command | /plan | Plan architecture before coding | +| Skill | tdd-workflow | TDD methodology guidance | +| Agent | code-reviewer | Post-implementation review | +| Model | Sonnet 4.6 | Recommended for this scope | + +### Section 3: Optimized Prompt — Full Version + +Present the complete optimized prompt inside a single fenced code block. +The prompt must be self-contained and ready to copy-paste. Include: +- Clear task description with context +- Tech stack (detected or specified) +- /command invocations at the right workflow stages +- Acceptance criteria +- Verification steps +- Scope boundaries (what NOT to do) + +For items that reference blueprint, write: "Use the blueprint skill to..." +(not `/blueprint`, since blueprint is a skill, not a command). + +### Section 4: Optimized Prompt — Quick Version + +A compact version for experienced ECC users. Vary by intent type: + +| Intent | Quick Pattern | +|--------|--------------| +| New Feature | `/plan [feature]. /tdd to implement. /code-review. /verify.` | +| Bug Fix | `/tdd — write failing test for [bug]. Fix to green. /verify.` | +| Refactor | `/refactor-clean [scope]. /code-review. /verify.` | +| Research | `Use search-first skill for [topic]. /plan based on findings.` | +| Testing | `/tdd [module]. /e2e for critical flows. /test-coverage.` | +| Review | `/code-review. Then use security-reviewer agent.` | +| Docs | `/update-docs. /update-codemaps.` | +| EPIC | `Use blueprint skill for "[objective]". Execute phases with /verify gates.` | + +### Section 5: Enhancement Rationale + +| Enhancement | Reason | +|-------------|--------| +| (what was added) | (why it matters) | + +### Footer + +> Not what you need? Tell me what to adjust, or make a normal task request +> if you want execution instead of prompt optimization. + +--- + +## Examples + +### Trigger Examples + +- "Optimize this prompt for ECC" +- "Rewrite this prompt so Claude Code uses the right commands" +- "帮我优化这个指令" +- "How should I prompt ECC for this task?" + +### Example 1: Vague Chinese Prompt (Project Detected) + +**User input:** +``` +帮我写一个用户登录页面 +``` + +**Phase 0 detects:** `package.json` with Next.js 15, TypeScript, Tailwind CSS + +**Optimized Prompt (Full):** +``` +使用项目现有技术栈（Next.js 15 + TypeScript + Tailwind CSS）实现用户登录页面。 + +技术要求： +- 沿用项目现有的组件结构和路由约定 +- 表单验证使用项目中已有的验证方案（检查是否已用 Zod/Yup/其他） +- 认证方式：沿用项目现有认证方案（如无，默认 JWT） +- 包含：邮箱/密码登录表单、表单验证、错误提示、加载状态、响应式布局 + +工作流： +1. /plan 先规划组件结构和认证流程，参考现有页面的模式 +2. /tdd 测试先行：编写登录表单的单元测试和认证流程的集成测试 +3. 实现登录页面和认证逻辑 +4. /code-review 审查实现 +5. /verify 验证所有测试通过且页面正常渲染 + +安全要求： +- 密码不明文传输 +- 防止暴力破解（rate limiting） +- XSS 防护 +- CSRF token + +验收标准： +- 所有测试通过，覆盖率 80%+ +- 页面在移动端和桌面端正常渲染 +- 登录成功跳转到 dashboard，失败显示错误信息 + +不要做： +- 不要实现注册页面 +- 不要实现忘记密码功能 +- 不要修改现有的路由结构 +``` + +### Example 2: Moderate English Prompt + +**User input:** +``` +Add a REST API endpoint for user profile updates with validation +``` + +**Phase 0 detects:** `go.mod` with Go 1.22, Chi router + +**Optimized Prompt (Full):** +``` +Add a REST API endpoint for user profile updates (PATCH /api/users/:id). + +Tech stack: Go 1.22 + Chi router (detected from project) + +Requirements: +- PATCH /api/users/:id — partial update of user profile +- Input validation for fields: name, email, avatar_url, bio +- Auth: require valid token, users can only update own profile +- Return 200 with updated user on success +- Return 400 with validation errors on invalid input +- Return 401/403 for auth failures +- Follow existing API patterns in the codebase + +Workflow: +1. /plan the endpoint structure, middleware chain, and validation logic +2. /tdd — write table-driven tests for success, validation failure, auth failure, not-found +3. Implement following existing handler patterns +4. /go-review +5. /verify — run full test suite, confirm no regressions + +Do not: +- Modify existing endpoints +- Change the database schema (use existing user table) +- Add new dependencies without checking existing ones first (use search-first skill) +``` + +### Example 3: EPIC Project + +**User input:** +``` +Migrate our monolith to microservices +``` + +**Optimized Prompt (Full):** +``` +Use the blueprint skill to plan: "Migrate monolith to microservices architecture" + +Before executing, answer these questions in the blueprint: +1. Which domain boundaries exist in the current monolith? +2. Which service should be extracted first (lowest coupling)? +3. Communication pattern: REST APIs, gRPC, or event-driven (Kafka/RabbitMQ)? +4. Database strategy: shared DB initially or database-per-service from start? +5. Deployment target: Kubernetes, Docker Compose, or serverless? + +The blueprint should produce phases like: +- Phase 1: Identify service boundaries and create domain map +- Phase 2: Set up infrastructure (API gateway, service mesh, CI/CD per service) +- Phase 3: Extract first service (strangler fig pattern) +- Phase 4: Verify with integration tests, then extract next service +- Phase N: Decommission monolith + +Each phase = 1 PR, with /verify gates between phases. +Use /save-session between phases. Use /resume-session to continue. +Use git worktrees for parallel service extraction when dependencies allow. + +Recommended: Opus 4.6 for blueprint planning, Sonnet 4.6 for phase execution. +``` + +--- + +## Related Components + +| Component | When to Reference | +|-----------|------------------| +| `configure-ecc` | User hasn't set up ECC yet | +| `skill-stocktake` | Audit which components are installed (use instead of hardcoded catalog) | +| `search-first` | Research phase in optimized prompts | +| `blueprint` | EPIC-scope optimized prompts (invoke as skill, not command) | +| `strategic-compact` | Long session context management | +| `cost-aware-llm-pipeline` | Token optimization recommendations |