重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
spec-gathering by oimiragieo/agent-studio
npx skills add https://github.com/oimiragieo/agent-studio --skill spec-gathering通过结构化提问收集用户需求,并生成一份经过验证的需求文档。此技能将模糊的任务描述转化为可操作的、结构化的需求。
核心原则: 提出聪明的问题,生成有效的结构化输出。仅此而已。
始终使用:
例外情况:
NO SPEC WRITING WITHOUT VALIDATED REQUIREMENTS FIRST
在进入规范创建阶段之前,需求必须得到用户的确认。
在与用户沟通之前,先了解项目结构。
步骤:
# Read project structure
cat .claude/context/product.md 2>/dev/null || echo "No product context"
cat .claude/context/tech-stack.md 2>/dev/null || echo "No tech stack"
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
如果提供了任务描述,请确认:
"我理解您想要:[任务描述]。是这样吗?有任何需要澄清的地方吗?"
如果未提供任务,请询问:
"您想要构建或修复什么?请描述您需要的功能、错误或更改。"
等待用户回复。
根据任务,确定工作流类型:
| 如果任务听起来像... | 工作流类型 |
|---|---|
| "添加功能 X"、"构建 Y" | feature |
| "从 X 迁移到 Y"、"重构 Z" | refactor |
| "修复 X 处的错误"、"调试 Y" | investigation |
| "从 X 迁移数据" | migration |
| 单一服务,小改动 | simple |
询问以确认:
"这听起来像是一个 [workflow_type] 任务。对吗?"
根据项目上下文和任务,建议涉及的区域:
"根据您的任务和项目结构,我认为这涉及:
- [service1] (主要) - [原因]
- [service2] (集成) - [原因]
还有其他涉及的服务或区域吗?"
等待确认或更正。
在手动收集需求之前,使用上下文压缩器技能(渐进式披露模式)来优化澄清过程:
Skill({
skill: 'context-compressor',
context: {
taskDescription: taskDescription,
projectContext: projectContext,
services: identifiedServices,
mode: 'progressive-disclosure',
},
});
上下文压缩器(渐进式披露模式)执行以下操作:
返回:
仅询问上下文压缩器识别的关键澄清问题:
预算: 最多 3-5 个澄清问题
流程:
首先询问 CRITICAL 优先级问题(安全性、数据丢失、破坏性变更)
如果预算允许,询问 HIGH 优先级问题(用户体验、架构、可扩展性)
对于 MEDIUM/LOW 优先级,使用带有默认值的 [ASSUMES:] 标记
收集答案并记录所有假设。
总结您的理解,包括澄清后的需求和假设:
"让我确认一下我的理解:
任务 : [摘要] 类型 : [workflow_type] 范围 : [受影响区域列表]
已澄清的需求 (已询问的问题):
- ✅ [问题] → [答案]
- ✅ [问题] → [答案]
- ✅ [问题] → [答案]
应用的智能默认值 (因预算或清晰度而未询问):
[ASSUMES: X] [ASSUMES: Y] [ASSUMES: Z]
成功标准 :
- [标准 1]
- [标准 2]
这正确吗?"
等待确认。如果用户对任何假设有异议,允许他们覆盖或请求调整。
在向用户确认需求和假设后,将收集的数据映射到模板令牌:
const tokens = {
// Required tokens
FEATURE_NAME: gatheredRequirements.taskName,
VERSION: '1.0.0',
AUTHOR: 'Claude',
DATE: new Date().toISOString().split('T')[0],
STATUS: 'draft',
// Required: Acceptance criteria (minimum 1, maximum 50)
ACCEPTANCE_CRITERIA_1: gatheredRequirements.criteria[0] || '[Define acceptance criterion 1]',
ACCEPTANCE_CRITERIA_2: gatheredRequirements.criteria[1] || '[Define acceptance criterion 2]',
ACCEPTANCE_CRITERIA_3: gatheredRequirements.criteria[2] || '[Define acceptance criterion 3]',
// Optional tokens (can be empty strings if not gathered)
TERM_1: gatheredRequirements.terms?.[0] || '',
TERM_2: gatheredRequirements.terms?.[1] || '',
TERM_3: gatheredRequirements.terms?.[2] || '',
HTTP_METHOD: gatheredRequirements.httpMethod || '',
ENDPOINT_PATH: gatheredRequirements.endpointPath || '',
PROJECT_NAME: gatheredRequirements.projectName || 'Agent Studio',
// Assumptions from context-compressor (optional but recommended)
ASSUMPTIONS_MADE: gatheredRequirements.assumptions.map(a => `- ${a}`).join('\n') || '',
CLARIFICATIONS_ASKED: gatheredRequirements.clarifications || 0,
};
渲染前的验证:
调用 template-renderer 技能来创建规范:
Skill({
skill: 'template-renderer',
args: {
templateName: 'specification-template',
outputPath: `.claude/context/artifacts/specifications/${featureNameSlug}-spec.md`,
tokens: tokens,
},
});
输出位置 : .claude/context/artifacts/specifications/[feature-name]-spec.md
渲染后验证:
# Check file created
SPEC_FILE=".claude/context/artifacts/specifications/[feature-name]-spec.md"
test -f "$SPEC_FILE" && echo "✓ Spec created" || echo "✗ Spec creation failed"
# Check no unresolved tokens
grep -E '[{]{2}' "$SPEC_FILE" && echo "✗ Unresolved tokens found" || echo "✓ All tokens resolved"
# Check YAML frontmatter valid
YAML_COUNT=$(head -50 "$SPEC_FILE" | grep -E "^---$" | wc -l)
test "$YAML_COUNT" -eq 2 && echo "✓ YAML valid" || echo "✗ YAML invalid"
在完成需求收集之前:
错误原因: 假设会导致构建错误的东西。
正确做法: 提出澄清问题。确认理解。
错误原因: 用户可能误解了您的总结。
正确做法: 始终进行总结并等待明确的确认。
错误原因: "让它更好" 是不可操作的。
正确做法: 获取具体信息:什么行为?什么结果?如何验证?
此技能与以下技能配合良好:
工作流链:
spec-gathering (→ context-compressor in Phase 4.5) → template-renderer → spec-critique → planner
上下文压缩器集成详情(渐进式披露模式):
输入: "为应用添加用户身份验证"
流程:
确认任务:"您想添加用户身份验证。是这样吗?"
在渐进式披露模式下调用上下文压缩器(阶段 4.5):
Skill({ skill: 'context-compressor', context: { taskDescription: "Add user authentication", projectContext: {...}, mode: 'progressive-disclosure' } });
上下文压缩器返回:
CRITICAL 问题(5 个预算中询问了 3 个):
应用的假设(使用 [ASSUMES:]):
识别范围:"这将涉及后端 API、数据库和前端登录页面。"
根据澄清和默认值定义成功标准
映射到令牌:
{
FEATURE_NAME: "User Authentication",
VERSION: "1.0.0",
AUTHOR: "Claude",
DATE: "2026-01-28",
STATUS: "draft",
ACCEPTANCE_CRITERIA_1: "Users can sign up with email and password",
ACCEPTANCE_CRITERIA_2: "Email verification required before login",
ACCEPTANCE_CRITERIA_3: "Users can reset password via email link",
ACCEPTANCE_CRITERIA_4: "Role-based access control working (Admin/User/Guest)",
ASSUMPTIONS_MADE: "- JWT tokens with 1-hour expiry\n- bcrypt cost factor 12\n- HTTPS required",
CLARIFICATIONS_ASKED: 3
}
Skill({
skill: 'template-renderer',
args: {
templateName: 'specification-template',
outputPath: '.claude/context/artifacts/specifications/user-authentication-spec.md',
tokens: tokens,
},
});
输出:
.claude/context/artifacts/specifications/user-authentication-spec.md 处渲染的规范输入: "页面加载缓慢"
流程:
输出: 包含具体页面、指标和成功标准的调查需求。
症状: "是"、"否"、"可以" 没有细节。
解决方案: 提出更具体的问题。提供选项:"您更喜欢 A、B 还是 C?"
症状: 每个答案都添加了新功能。
解决方案: 明确记录"超出范围"。确认:"我们应该将此包含在此任务中,还是留待以后处理?"
| 反模式 | 失败原因 | 正确方法 |
|---|---|---|
| 模糊需求 ("让它快") | 不可衡量或测试 | 指定确切指标:"P95 响应时间 <100ms" |
| 缺少非功能性需求 | 质量属性被遗忘,直到为时已晚 | 始终捕获性能、安全性和可扩展性需求 |
| 没有超出范围部分 | 实施过程中范围蔓延 | 明确记录此任务不包含的内容 |
| 跳过用户确认 | 需求被误解并错误实施 | 在移交前与用户确认所有需求 |
| 未记录边缘情况 | 在质量保证期间发现错误处理漏洞 | 记录空输入、错误数据、超时和并发访问情况 |
开始前: 读取 .claude/context/memory/learnings.md
完成后:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.md假设中断:如果不在内存中,则未发生。
每周安装次数
63
仓库
GitHub 星标数
19
首次出现
2026年1月27日
安全审计
安装于
github-copilot61
gemini-cli60
opencode59
codex59
kimi-cli59
amp59
Gather user requirements through structured questioning and produce a validated requirements document. This skill transforms vague task descriptions into actionable, structured requirements.
Core principle: Ask smart questions, produce valid structured output. Nothing else.
Always:
Exceptions:
NO SPEC WRITING WITHOUT VALIDATED REQUIREMENTS FIRST
Requirements must be confirmed by the user before proceeding to spec creation.
Understand the project structure before engaging the user.
Steps:
# Read project structure
cat .claude/context/product.md 2>/dev/null || echo "No product context"
cat .claude/context/tech-stack.md 2>/dev/null || echo "No tech stack"
If a task description was provided, confirm it:
"I understand you want to: [task description]. Is that correct? Any clarifications?"
If no task was provided, ask:
"What would you like to build or fix? Please describe the feature, bug, or change you need."
Wait for user response.
Based on the task, determine the workflow type:
| If task sounds like... | Workflow Type |
|---|---|
| "Add feature X", "Build Y" | feature |
| "Migrate from X to Y", "Refactor Z" | refactor |
| "Fix bug where X", "Debug Y" | investigation |
| "Migrate data from X" | migration |
| Single service, small change | simple |
Ask to confirm:
"This sounds like a [workflow_type] task. Does that seem right?"
Based on the project context and task, suggest affected areas:
"Based on your task and project structure, I think this involves:
- [service1] (primary) - [why]
- [service2] (integration) - [why]
Any other services or areas involved?"
Wait for confirmation or correction.
Before gathering requirements manually, use the context-compressor skill (progressive disclosure mode) to optimize the clarification process:
Skill({
skill: 'context-compressor',
context: {
taskDescription: taskDescription,
projectContext: projectContext,
services: identifiedServices,
mode: 'progressive-disclosure',
},
});
Context-Compressor (progressive disclosure mode) performs:
Returns:
Ask only the critical clarification questions identified by context-compressor:
Budget: 3-5 clarification questions maximum
Process:
Ask CRITICAL priority questions first (security, data loss, breaking changes)
Ask HIGH priority questions if budget remains (UX, architecture, scalability)
For MEDIUM/LOW priorities, use [ASSUMES:] notation with defaults
Collect answers and document all assumptions.
Summarize what you understood, including clarified requirements and assumptions:
"Let me confirm I understand:
Task : [summary] Type : [workflow_type] Scope : [list of affected areas]
Clarified Requirements (questions asked):
- ✅ [Question] → [Answer]
- ✅ [Question] → [Answer]
- ✅ [Question] → [Answer]
Smart Defaults Applied (not asked due to budget or clarity):
[ASSUMES: X] [ASSUMES: Y] [ASSUMES: Z]
Success Criteria :
- [criterion 1]
- [criterion 2]
Is this correct?"
Wait for confirmation. If user objects to any assumption, allow them to override or request adjustment.
After confirming requirements and assumptions with user, map gathered data to template tokens:
const tokens = {
// Required tokens
FEATURE_NAME: gatheredRequirements.taskName,
VERSION: '1.0.0',
AUTHOR: 'Claude',
DATE: new Date().toISOString().split('T')[0],
STATUS: 'draft',
// Required: Acceptance criteria (minimum 1, maximum 50)
ACCEPTANCE_CRITERIA_1: gatheredRequirements.criteria[0] || '[Define acceptance criterion 1]',
ACCEPTANCE_CRITERIA_2: gatheredRequirements.criteria[1] || '[Define acceptance criterion 2]',
ACCEPTANCE_CRITERIA_3: gatheredRequirements.criteria[2] || '[Define acceptance criterion 3]',
// Optional tokens (can be empty strings if not gathered)
TERM_1: gatheredRequirements.terms?.[0] || '',
TERM_2: gatheredRequirements.terms?.[1] || '',
TERM_3: gatheredRequirements.terms?.[2] || '',
HTTP_METHOD: gatheredRequirements.httpMethod || '',
ENDPOINT_PATH: gatheredRequirements.endpointPath || '',
PROJECT_NAME: gatheredRequirements.projectName || 'Agent Studio',
// Assumptions from context-compressor (optional but recommended)
ASSUMPTIONS_MADE: gatheredRequirements.assumptions.map(a => `- ${a}`).join('\n') || '',
CLARIFICATIONS_ASKED: gatheredRequirements.clarifications || 0,
};
Validation Before Rendering:
Invoke the template-renderer skill to create the specification:
Skill({
skill: 'template-renderer',
args: {
templateName: 'specification-template',
outputPath: `.claude/context/artifacts/specifications/${featureNameSlug}-spec.md`,
tokens: tokens,
},
});
Output Location : .claude/context/artifacts/specifications/[feature-name]-spec.md
Post-Rendering Verification:
# Check file created
SPEC_FILE=".claude/context/artifacts/specifications/[feature-name]-spec.md"
test -f "$SPEC_FILE" && echo "✓ Spec created" || echo "✗ Spec creation failed"
# Check no unresolved tokens
grep -E '[{]{2}' "$SPEC_FILE" && echo "✗ Unresolved tokens found" || echo "✓ All tokens resolved"
# Check YAML frontmatter valid
YAML_COUNT=$(head -50 "$SPEC_FILE" | grep -E "^---$" | wc -l)
test "$YAML_COUNT" -eq 2 && echo "✓ YAML valid" || echo "✗ YAML invalid"
Before completing requirements gathering:
Why it's wrong: Assumptions lead to building the wrong thing.
Do this instead: Ask clarifying questions. Confirm understanding.
Why it's wrong: User may have misunderstood your summary.
Do this instead: Always summarize and wait for explicit confirmation.
Why it's wrong: "Make it better" is not actionable.
Do this instead: Get specific: What behavior? What outcome? How to verify?
This skill works well with:
Workflow Chain :
spec-gathering (→ context-compressor in Phase 4.5) → template-renderer → spec-critique → planner
Context-Compressor Integration Details (Progressive Disclosure Mode) :
Input: "Add user authentication to the app"
Process:
Confirm task: "You want to add user authentication. Is this correct?"
Invoke context-compressor in progressive disclosure mode (Phase 4.5):
Skill({ skill: 'context-compressor', context: { taskDescription: "Add user authentication", projectContext: {...}, mode: 'progressive-disclosure' } });
Context-compressor returns:
CRITICAL questions (3 asked of 5 budget):
Assumptions applied (with [ASSUMES:]):
Identify scope: "This will touch the backend API, database, and frontend login page."
Define success criteria based on clarifications and defaults
Map to tokens:
{
FEATURE_NAME: "User Authentication",
VERSION: "1.0.0",
AUTHOR: "Claude",
DATE: "2026-01-28",
STATUS: "draft",
ACCEPTANCE_CRITERIA_1: "Users can sign up with email and password",
ACCEPTANCE_CRITERIA_2: "Email verification required before login",
ACCEPTANCE_CRITERIA_3: "Users can reset password via email link",
ACCEPTANCE_CRITERIA_4: "Role-based access control working (Admin/User/Guest)",
ASSUMPTIONS_MADE: "- JWT tokens with 1-hour expiry\n- bcrypt cost factor 12\n- HTTPS required",
CLARIFICATIONS_ASKED: 3
}
Skill({
skill: 'template-renderer',
args: {
templateName: 'specification-template',
outputPath: '.claude/context/artifacts/specifications/user-authentication-spec.md',
tokens: tokens,
},
});
Output:
.claude/context/artifacts/specifications/user-authentication-spec.mdInput: "The page loads slowly"
Process:
Output: Investigation requirements with specific pages, metrics, and success criteria.
Symptoms: "Yes", "No", "That's fine" without detail.
Solution: Ask more specific questions. Provide options: "Would you prefer A, B, or C?"
Symptoms: Every answer adds new features.
Solution: Document "Out of Scope" explicitly. Confirm: "Should we include this in this task or save for later?"
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Vague requirements ("make it fast") | Not measurable or testable | Specify exact metrics: "P95 response time <100ms" |
| Missing NFRs | Quality attributes forgotten until too late | Always capture performance, security, scalability requirements |
| No out-of-scope section | Scope creep during implementation | Explicitly document what this task does NOT include |
| Skipping user confirmation | Requirements misunderstood and implemented incorrectly | Confirm all requirements with the user before handoff |
| No edge cases documented | Error handling gaps discovered during QA | Document empty input, bad data, timeout, and concurrent access cases |
Before starting: Read .claude/context/memory/learnings.md
After completing:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.mdASSUME INTERRUPTION: If it's not in memory, it didn't happen.
Weekly Installs
63
Repository
GitHub Stars
19
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
github-copilot61
gemini-cli60
opencode59
codex59
kimi-cli59
amp59
超能力技能使用指南:AI助手技能调用优先级与工作流程详解
53,700 周安装
SSH 技能大全:远程连接、文件传输、端口转发与安全配置完整指南
411 周安装
React Three Fiber 几何体教程 - 3D 形状创建与参数详解
413 周安装
SVG滤镜与CSS动画创建逼真水波效果 - Web Wave Designer海洋水景设计指南
62 周安装
Google Gemini CLI PR 评论处理助手 - 自动化审查 GitHub Pull Request 反馈
418 周安装
best-minds:基于专家模拟的AI提问框架,提升LLM回答质量与专业性
407 周安装
使用 Packer 构建 Windows 镜像:AWS/Azure 平台指南与 WinRM 配置
413 周安装