Expression Precision

Expression Precision is an intent-clarification skill that turns vague thoughts, feelings, feedback, requirements, and agent instructions into precise, reusable language.

Live Demo · MIT License · Deployment Guide · Demo Script · Hackathon Submission Draft

Most writing assistants and AI agents move too early. Expression Precision first detects ambiguity, identifies the missing information needed to describe the situation accurately, and asks guided multi-select questions. It produces final wording, or a clarified task for another agent, only after the meaning is specific enough to express without invented facts.

Hackathon Track

Recommended main track: Skill

The Codex Skill is the core reusable product. The bilingual web demo makes the behavior easy to understand, test, and share with both human users and teams building agent workflows.

Do not select both Skill and Agent as main tracks for the UCWS Singapore Hackathon 2026. The event announcement states that only Deep Research can be selected together with one of the three main tracks: Agent, Skill, or Application.

What It Does

1. Detects vague words, unclear references, unsupported judgments, and missing facts.
2. Identifies which information would materially change the final expression.
3. Asks concise multi-select questions with a None of the above path.
4. Uses concrete facts supplied by the user without asking them to repeat information.
5. Produces a Precise Name, Concrete Explanation, and Copyable Expression.

Why It Matters

People often know that something feels wrong, important, or promising before they can describe it clearly. That gap causes weak feedback, ambiguous requirements, avoidable conflict, and generic AI-generated writing.

Expression Precision helps users move from:

“My teammate is kind of difficult.”

to:

“They have a higher personal standard for office hygiene and comfort, but they handle those preferences themselves without adding work for others.”

Repository Structure

.
├── .agents/plugins/marketplace.json
├── .github/workflows/demo-ci.yml
├── plugins/expression-precision/
│   ├── .codex-plugin/plugin.json
│   └── skills/expression-precision/
├── demo/
│   ├── app/
│   ├── components/
│   ├── lib/
│   └── package.json
└── docs/
    ├── DEMO_SCRIPT.md
    ├── DEPLOYMENT.md
    └── SUBMISSION.md

Use As A Skill

Expression Precision is packaged as a Codex Plugin and the underlying Skill is portable. Codex users can install the plugin from this GitHub repository. Claude Code users can copy the SKILL.md folder into Claude's local skills directory.

Install In Codex

Install from the public GitHub repository:

codex plugin marketplace add 75yang/expression-precision
codex plugin install expression-precision@expression-precision

Then invoke the skill in Codex:

$expression-precision

I feel like my teammate is difficult, but I cannot explain why.

You can also ask naturally:

Use expression-precision to clarify this feedback: The product experience feels bad.

Manual Codex Install

If you do not want to install the full plugin, copy only the skill folder:

mkdir -p ~/.codex/skills/expression-precision
cp -R plugins/expression-precision/skills/expression-precision/* ~/.codex/skills/expression-precision/

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills\expression-precision"
Copy-Item -Recurse -Force "plugins\expression-precision\skills\expression-precision\*" "$env:USERPROFILE\.codex\skills\expression-precision\"

Use In Claude Code

Claude Code can use the same Skill body, but it does not use the Codex plugin manifest. Copy the skill folder into Claude's skills directory:

mkdir -p ~/.claude/skills/expression-precision
cp -R plugins/expression-precision/skills/expression-precision/* ~/.claude/skills/expression-precision/

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills\expression-precision"
Copy-Item -Recurse -Force "plugins\expression-precision\skills\expression-precision\*" "$env:USERPROFILE\.claude\skills\expression-precision\"

Then ask Claude Code:

Use expression-precision to clarify this:

I feel stuck about this decision.

The portable part is plugins/expression-precision/skills/expression-precision/SKILL.md plus its references/ folder. The Codex-specific plugin metadata lives in plugins/expression-precision/.codex-plugin/plugin.json.

Run The Web Demo

cd demo
npm install
cp .env.example .env.local

Choose a model provider and add a server-side API key to demo/.env.local:

MODEL_PROVIDER=qwen
DASHSCOPE_API_KEY=your-new-key
QWEN_MODEL=qwen-plus
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

The example above uses Alibaba Cloud Model Studio's China (Beijing) endpoint. Use https://dashscope-intl.aliyuncs.com/compatible-mode/v1 only with a Singapore-region key. DashScope API keys are region-specific.

npm run preview

Open:

• Product website: http://localhost:3000
• Interactive Studio: http://localhost:3000/app

The Studio includes a deterministic guided sample, so the full experience remains demonstrable when the live API is unavailable.

npm run dev is useful while editing the site. Use npm run preview for final local testing and hackathon demonstrations.

API Key Architecture

API keys are sensitive credentials and must never be committed, placed in browser-side source code, written to local storage, or sent to analytics.

The public hackathon demo uses this request path:

Visitor browser → Next.js server route → Model API

The server route:

• uses a deployment-only provider key from server-side environment variables;
• never sends the key to browser-side code or API responses;
• applies a basic per-instance request limit per IP address;
• rejects inputs longer than 6,000 characters;
• exposes only a safe /api/status response that reports whether the live agent is configured.

For a public hackathon deployment, create a dedicated project key, set a small provider-side budget or alert, keep the per-IP request limit enabled, and rotate or delete the key after the event. If you need a no-shared-key mode for self-hosted experiments, set VISITOR_KEY_ONLY=true and let users provide temporary request keys.

Deploy The Demo

The simplest deployment path is Vercel:

1. Import the GitHub repository into Vercel.
2. Set the project root directory to demo.
3. Add DASHSCOPE_API_KEY as a server-side environment variable so visitors can use the demo without pasting a key.
4. The committed vercel.json defaults the public build to Qwen and sets DEMO_REQUESTS_PER_HOUR=30.
5. Optionally use MODEL_PROVIDER=openai, OPENAI_API_KEY, and OPENAI_MODEL instead.
6. Optionally set DEMO_REQUESTS_PER_HOUR to control the per-IP hourly limit.
7. Deploy and add the public URL to the hackathon submission.

Never expose any provider API key in browser-side code or commit .env.local.

See docs/DEPLOYMENT.md for the public-demo architecture, safe bring-your-own-key approach, and verification checklist.

Validation

# Validate the plugin
python <plugin-creator>/scripts/validate_plugin.py plugins/expression-precision

# Validate the skill
python <skill-creator>/scripts/quick_validate.py \
  plugins/expression-precision/skills/expression-precision

# Validate the demo
cd demo
npm run lint
npm run build

中文简介

Expression Precision 是一个帮助用户把模糊感觉、想法、反馈和需求转化为精准语言的交互式 Skill。

它不会立刻润色原句，而是先定位模糊点，分析缺失信息，通过可多选问题和“都不是”分支逐步澄清，最后生成：

• 精准命名
• 具体解释
• 可复制表达

公开 Demo 使用服务端环境变量中的比赛专用模型 API Key，访客无需填写任何 Key，打开网页即可体验。Key 不会进入浏览器代码或 GitHub 仓库；成本控制通过每 IP 限流、输入长度限制和阿里云百炼后台预算/预警完成。当前 Demo 支持 OpenAI，也支持通过阿里云百炼 OpenAI-compatible 接口调用 Qwen。

中文使用说明

在 Codex 中安装

推荐通过 GitHub 仓库安装完整 Codex Plugin：

codex plugin marketplace add 75yang/expression-precision
codex plugin install expression-precision@expression-precision

安装后在 Codex 中调用：

$expression-precision

我觉得这个同事有点事儿，但说不清具体哪里不对。

也可以自然语言调用：

Use expression-precision to clarify this: 我觉得这个产品体验不好。

手动安装到 Codex

如果只想使用 Skill 本体，可以复制 Skill 文件夹：

mkdir -p ~/.codex/skills/expression-precision
cp -R plugins/expression-precision/skills/expression-precision/* ~/.codex/skills/expression-precision/

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills\expression-precision"
Copy-Item -Recurse -Force "plugins\expression-precision\skills\expression-precision\*" "$env:USERPROFILE\.codex\skills\expression-precision\"

在 Claude Code 中使用

Claude Code 可以复用同一套 Skill 说明，但不使用 Codex 的 .codex-plugin/plugin.json。把 Skill 文件夹复制到 Claude 的 skills 目录：

mkdir -p ~/.claude/skills/expression-precision
cp -R plugins/expression-precision/skills/expression-precision/* ~/.claude/skills/expression-precision/

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills\expression-precision"
Copy-Item -Recurse -Force "plugins\expression-precision\skills\expression-precision\*" "$env:USERPROFILE\.claude\skills\expression-precision\"

然后在 Claude Code 中使用：

Use expression-precision to clarify this:

我对这个决定有点卡住。

可移植的核心是 plugins/expression-precision/skills/expression-precision/SKILL.md 和同目录下的 references/ 文件夹；Codex Plugin 的展示、图标和安装元数据在 plugins/expression-precision/.codex-plugin/plugin.json。