Docs & Knowledge · daymade/claude-code-skills

prompt-optimizer

Name: prompt-optimizer
Author: daymade/claude-code-skills

Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. This skill should be used when users provide loose requirements, ambiguous feature descriptions, or need to enhance prompts for AI-generated code, products, or documents. Triggers include requests to "optimize my prompt", "improve this requirement", "make this more specific", or when raw requirements lack detail and structure.

L1 Basic · Source registration onlyV1 Commit-PinnedDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Pure prompt orchestration: The entire mechanism relies on a "four-tier enhancement workflow"—transforming vague requirements using EARS syntax, grounding them in domain theories, extracting realistic examples, and packaging them into an enhanced prompt with a fixed structural skeleton.

prompt-optimizer/SKILL.md

**Four-layer enhancement process:** 1. **EARS syntax transformation** - Convert descriptive language to normative specifications 2. **Domain theory grounding** - Apply relevant industry frameworks (GTD, BJ Fogg, Gestalt, etc.) 3. **Example extraction** - Surface concrete use cases with real data 4. **Structured prompt generation** - Format using Role/Skills/Workflows/Examples/Formats framework

What is happening here: This is both the ceiling and the entirety of this skill. With zero scripts, tools, or network calls, its value lies completely within these orchestration instructions that translate "colloquial requirements" into "standardized statements + theoretical foundations + realistic examples + output constraints".

Implementation of the five EARS patterns: Ubiquitous, Event-driven, State-driven, Conditional, and Unwanted behavior each have fixed sentence patterns, paired with before/after comparisons and a transformation checklist (making conditions explicit, adding triggers, quantifying metrics, splitting atomic statements, removing ambiguous words).

prompt-optimizer/SKILL.md

**Five core patterns:** 1. **Ubiquitous**: `The system shall <action>` 2. **Event-driven**: `When <trigger>, the system shall <action>` 3. **State-driven**: `While <state>, the system shall <action>` 4. **Conditional**: `If <condition>, the system shall <action>` 5. **Unwanted behavior**: `If <condition>, the system shall prevent <unwanted action>`

What is happening here: EARS (the requirement writing methodology proposed by Rolls-Royce in 2009) was originally designed for systems engineering; here, it serves as a "canonical syntax" for prompts, ensuring every requirement is paired with clear triggering conditions and verifiable outcomes.

Domain theory grounding mechanism: It first identifies the domain based on requirement keywords, selects 2–4 complementary theories from a 10-domain catalog, maps theoretical principles to specific features, and explicitly cites theory names within the prompt.

prompt-optimizer/SKILL.md

**Selection process:** 1. Identify primary domain from requirement keywords 2. Match to 2-4 complementary theories 3. Apply theory principles to specific features 4. Cite theories in enhanced prompt for credibility

What is happening here: It prevents the resulting specification from looking like an arbitrary "wishlist of features"—every design trade-off traces back to an established framework (e.g., GTD, BJ Fogg B=MAT, Hick's Law, Zero Trust). Theories serve as both a design scaffold and a badge of credibility.

The theory catalog itself is a major asset: 10 domains (productivity, behavior change, UX, gamification, learning, data visualization, e-commerce, information architecture, security, accessibility) containing 38 numbered theoretical entries, supported by a selection workflow ("pick 2–4 theories → map to features and workflows → cite for credibility") and a complete selection walkthrough.

prompt-optimizer/references/domain_theories.md

## How to Select Theories 1. **Identify the domain** from user requirements 2. **Match to primary objective** (engagement, learning, conversion, etc.) 3. **Select 2-4 relevant theories** that complement each other 4. **Apply principles** to specific features and workflows 5. **Cite theories** in enhanced prompts to add credibility

What is happening here: This represents the concrete substance behind the single line "40+ theories mapped to 10 domains" for `domain_theories.md` in SKILL.md—theory titles plus three to five concise key takeaways, sufficient for models to select and cite without derivation steps.

Fixed five-section output skeleton: Role / Skills / Workflows / Examples / Formats, where examples strictly mandate realistic data ("Real data, not 'Example 1', 'Example 2'"), delivering a ready-to-copy Markdown specification.

prompt-optimizer/SKILL.md

- **Concrete examples**: Real data, not "Example 1", "Example 2"

What is happening here: The prompt is structured as a "construction blueprint for downstream agents"—roles must target niche domains, workflows must be phased, and formats must be verifiable, thereby curtailing unpredictable hallucinations from downstream models.

Sequential, diagnostic six-step workflow: It begins by diagnosing weaknesses in the original requirement (overly broad, missing triggers, vague actions, lack of constraints), then progressively converts them to EARS, selects theories, extracts examples, generates the prompt, and presents the output in a fixed six-part structure.

prompt-optimizer/SKILL.md

### Step 1: Analyze Original Requirement Identify weaknesses: - **Overly broad** - "Add user authentication" → Missing password requirements, session management - **Missing triggers** - "Send notifications" → Missing when/why notifications trigger - **Ambiguous actions** - "Make it user-friendly" → No measurable usability criteria - **No constraints** - "Process payments" → Missing security, compliance requirements

What is happening here: The weakness categorization in Step 1 serves as the benchmark for the entire methodology—without it, EARS conversion is merely template substitution; with it, rewriting has targeted direction (adding conditions, metrics, and boundaries).

Advanced handbook for complex requirements: Multi-stakeholder requirements (per-role EARS statements, explicit role constraints, and nested permissions), non-functional requirements (quantified thresholds across performance, security, scalability, and reliability), and complex conditional logic (nested AND/OR, precedence handling, and fallback branches).

prompt-optimizer/references/advanced_techniques.md

1. Quantify constraints explicitly (no vague terms like "fast" or "secure") 2. Specify measurement methods (how to verify the requirement) 3. Include threshold values (acceptable ranges) 4. Define degradation behavior (what happens when thresholds are exceeded)

What is happening here: Vague adjectives like "fast" or "secure" are forced into verifiable metrics, such as "95% of requests return within 200ms", "lock out after 5 failures for 30 minutes", or "bcrypt cost factor 12"—a crucial tier elevating this skill from simple rephrasing to authoring acceptance criteria.

On-demand reference loading with a lean main skeleton: SKILL.md uses a Resources section explaining when to load each reference, sparing the model from reading everything at once (195-line main file + 1,014 lines of references).

prompt-optimizer/SKILL.md

- **`references/domain_theories.md`** - 40+ theories mapped to 10 domains (productivity, UX, gamification, learning, e-commerce, security, etc.)

What is happening here: A quintessential implementation of progressive disclosure—the main file governs workflows and trigger evaluation, while detailed specifics (complete EARS syntax, theory catalogs, four full case studies, and advanced techniques) reside in four on-demand reference files.

2Core Capabilities

01Vague requirements → EARS canonical statement transformation (five pattern formats + transformation checklist + before/after comparisons)

02Domain theory matching and mapping (10-domain catalog, selecting 2–4 complementary theories, mapping to specific features, and explicit citation)

03Quantified rewriting of non-functional requirements (performance, security, scalability, reliability, requiring explicit thresholds + measurement methods + degradation behavior)

04Multi-stakeholder and role-based permissions EARS expansion (role-segregated statements, hierarchical permissions, contextual access + default-deny branches)

05Complex conditional logic modeling (nested conditions, explicit Boolean operators, conflict prioritization, parenthesis-defined precedence, fallback handling)

06Realistic data example extraction (mandating realistic / specific / varied [success, error, edge-case] / testable criteria, prohibiting placeholder labels)

07Structured output presentation (Original Requirement / Identified Issues / EARS Transformation / Domain & Theories / Enhanced Prompt + How to use)

08Four complete before/after case studies + Transformation Pattern Template (including original Chinese requirements and English translations)

3External Dependencies

Kind	Dependency / Endpoint
network	出处引用链接（方法论来源展示，运行时脚本并不访问）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Can be auto-loaded

For Administrators

Evidence & Triggers (File Paths & Excerpts)

SKILL.md: Pure prompt directives and rule text, devoid of script execution and external side effects.

Audit Notes: Pure prompt-based skill: A full recursive inspection (including hidden files) reveals only SKILL.md and four markdown files under references/{advanced_techniques,domain_theories,ears_syntax,examples}.md, with no scripts/, no hooks, and no executable binaries. The text contains zero curl/wget/urllib/network calls, no reading of environment variables or credentials, no file writes, and no instructions directing the agent to execute system commands—presenting zero code-level attack surface. Potential risks are confined to the conversational and content layer: rewriting may standardize and propagate prompt injections present in raw inputs (lending an air of legitimacy to untrusted inputs), theoretical citations could be misconstrued as quality or security endorsements, and sample security configurations in references do not represent audit conclusions. None of these present host-side security vulnerabilities.

5Second-Pass Verification

[ok] 资产面：是否存在脚本、hooks 或隐藏文件 — find prompt-optimizer -type f（含隐藏）只有 5 个文件：SKILL.md、references/{advanced_techniques,domain_theories,ears_syntax,examples}.md。无 scripts/、无 tests/、无 frontmatter 里的 allowed-tools 之外的配置键（frontmatter 仅 name/description 两键）。第一遍『纯 prompt』结论成立。
[ok] 外部依赖反例：是否有漏掉的网络/凭证/执行面 — 全目录 token 扫描：无 curl/wget/urllib/requests/子进程调用/环境变量读取/写文件指令；https?:// 仅 3 处且都是出处引用（mp.weixin.qq.com 在 SKILL.md 与 examples.md），其余命中（token、api、secret 等）均出现在 EARS 示例文本里（如 password_reset_tokens 表、POST /api/auth/reset-password），是指被改写的示例需求而非 skill 的依赖。external_deps 因此只列出处引用一条，并注明运行时并不访问。
[discrepancy] 宣传口径核对：domain_theories.md 是否真有 40+ 理论与 10 个域 — SKILL.md 的 Resources 段写 `40+ theories mapped to 10 domains`。第二遍用脚本统计：域数 10 属实（Productivity 5、Behavior Change 4、UX 6、Gamification 4、Learning 5、DataViz 3、E-commerce 3、IA 3、Security 3、Accessibility 2），但编号理论条目合计 38 条，未达 40+；若把跨域重复的 Self-Determination Theory、Gestalt Principles 去重，唯一理论数更少。属宣传性口径略偏大，不影响目录可用性，但『40+』不应被当作已核实的数字引用。
[ok] EARS 五范式与 checklist 是否在两处一致 — SKILL.md 的 Step 2 列出五范式与 6 项 checklist；ears_syntax.md 对同一五范式给出 Format/English/Use when/Example 完整四段（含中文句式 `当 <trigger> 时,系统应 <action>`）与同一份扩展 checklist（多出『Define the actor』『Specify measurable outcomes』两项）、再加多条件事件与分支动作两种复杂形态。两处无冲突，reference 是超集。
[ok] 输出格式声明 vs 实际骨架（夸大检查） — SKILL.md Step 5 的骨架（Role/Skills/Workflows/Examples/Formats）、Step 6 的六段式结果格式、examples.md 的 Transformation Pattern Template 三处骨架一致；description 宣称的『precise, well-structured specifications』由 Formats 段的『File types, structure requirements / Technical constraints / Deliverable checklist』承载。无未兑现承诺，也没有声称会验证产出。
[ok] 非功能需求与复杂条件的具体落地方式是否真实存在 — advanced_techniques.md 实读：非功能四类各给 3-8 条量化范式（200ms/95%、1.5s FCP/90%、TLS 1.3、tokenize 卡号、retry 3×2s、1,000/s 排队、fraud score>70）；复杂条件给出嵌套层级、显式布尔、优先级、括号与兜底五步与多段示例。第一遍『量化阈值』结论逐条可定位。
[ok] 案例数量与出处标注 — examples.md 标题清单：Example 1 拖延症消除器、Example 2 电商商品页、Example 3 学习仪表盘、Example 4 密码重置安全，加一个 Transformation Pattern Template；SKILL.md Resources 段自述『Four complete transformation examples (procrastination app, e-commerce product page, learning dashboard, password reset security)』与实读标题逐一对应。出处标注在 SKILL.md 与 examples.md 出现两次且互为一致。
[ok] 对『改写是否会被当作事实核验』的找反例 — 通读 5 个文件，未发现任何『验证需求真实性/可达性』的步骤或声明，也没有针对输出自检的机制（checklist 只约束句式与粒度）。故 verdict.risks 中『只保证写法规范不保证内容正确』成立，且不构成夸大——SKILL.md 也未做此承诺。

6Verdict & Scenarios

Turns requirements engineering into an executable workflow: Diagnosing weaknesses → EARS five-pattern rewrite → Theoretical grounding → Realistic examples → Five-section skeleton, with concrete sentence structures or checklists for every step.

A ready-to-use arsenal in its theory catalog: 38 attributed frameworks across 10 domains, complete with selection workflows and end-to-end examples, grounding impromptu feature ideas into established design paradigms.

The advanced handbook forces vague adjectives into measurable acceptance criteria (200ms/95%, TLS 1.3, retry 3×2s, bcrypt cost 12), making non-functional requirements verifiable.

Strict output discipline: Bans placeholder examples, eliminates vague terms, enforces one action per requirement, and delivers a copy-pasteable specification with fill-in-the-blank templates.

Zero execution footprint ensures universal host compatibility: Requires no dependencies, no file I/O, and no network access; this pure-text methodology can be imported directly into other skills or team guidelines.

Best for: Ideal for scenarios requiring conversational, vague feature concepts to be converted into executable specifications: product managers or tech leads drafting specifications before implementation, formalizing single-sentence ideas before feeding them to AI code generators, translating and structuring Chinese requirements into English specifications for downstream agents, or projects needing quantified thresholds for non-functional metrics (performance/security). Also well-suited as an embedded "requirement standardization" sub-workflow inside other skills thanks to its zero-dependency, pure-text nature.

Not for: Not suitable for scenarios requiring factual verification or technical correctness endorsement (it guarantees syntactic rigor, not factual validity); not suitable for established, precise specifications (no rewriting needed); not suitable for workflows expecting automatic code generation or acceptance test execution (it produces no implementation, runs no tests, and has zero execution capabilities); and not suitable for formal security or compliance documentation—theoretical references and sample parameters do not constitute audit findings.

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload prompt-optimizer.tar.gz

sha256: a62c59842d84fe47…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.