AgentSkillsCN

Spec Writer

规范撰写者

SKILL.md

Spec Writer - Rigorous Project Specification

Use this skill when the user mentions "write spec", "project spec", "define goals", "spec properties", "project definition", or wants to create or update a comprehensive project specification.

Purpose

A spec is the source of truth for a project's direction. It answers: What are we building? Why? What's in scope? How do we know when we're done?

This skill guides the creation of rigorous specs through property-based validation - ensuring all necessary aspects are addressed without enforcing a rigid format.

Required Properties

Every good spec must address these properties. The format can vary, but the information must be present.

1. Purpose (Required)

Question: Why does this project exist? What problem does it solve?

  • •Not just "what it does" but "why it matters"
  • •Who benefits and how
  • •What would be missing if this didn't exist

2. Scope (Required)

Question: What's explicitly IN and OUT?

In Scope:

  • •Concrete capabilities the project will have
  • •Features that are committed

Out of Scope (equally important):

  • •What this project deliberately won't do
  • •Adjacent problems it won't solve
  • •Features explicitly deferred

3. Success Criteria (Required)

Question: How do we know when this is "done" or "working"?

  • •Observable, verifiable conditions
  • •Not vague ("works well") but specific ("passes all integration tests", "handles 1000 concurrent users")
  • •Can be different for different phases

4. Current Phase (Required)

Question: Where are we now in the project lifecycle?

  • •What phase/milestone is active
  • •What "done" looks like for THIS phase
  • •What triggers moving to next phase

Contextual Properties

Include these when relevant to the project:

Architecture Decisions

Key technical choices and their rationale.

  • •What was decided
  • •Why (constraints, tradeoffs)
  • •Alternatives considered
  • •Consequences/implications

Constraints

Limitations that shape the solution.

  • •Technical (language, platform, dependencies)
  • •Business (timeline, budget, resources)
  • •External (APIs, regulations, compatibility)

Dependencies

What this project relies on.

  • •External services/APIs
  • •Libraries/frameworks
  • •Other internal projects
  • •People/expertise

Risks

What could derail the project.

  • •Technical risks (complexity, unknowns)
  • •External risks (dependencies, changes)
  • •Mitigation strategies

Open Questions

Unresolved decisions that need answers.

  • •What's uncertain
  • •What information would help decide
  • •When decisions need to be made

Writing a Spec

Process

  1. •Start with Purpose: Write 2-3 sentences on why this exists
  2. •Define Scope: List what's in, what's out
  3. •Set Success Criteria: How will we verify success?
  4. •Identify Current Phase: Where are we now?
  5. •Add Context: Architecture, constraints, risks as relevant
  6. •Review for Gaps: Does someone reading this know what to build?

Validation Checklist

A spec is complete when you can answer YES to all:

  • • Could a new team member understand the project's purpose?
  • • Is it clear what's NOT in scope?
  • • Are success criteria specific and verifiable?
  • • Is the current phase and its goals clear?
  • • Are key technical decisions documented with rationale?
  • • Are significant risks identified?

Style Guidelines

  • •Be specific: "Fast" → "Responds within 200ms"
  • •Be honest: Include unknowns and risks
  • •Be concise: Dense information, not lengthy prose
  • •Update regularly: A stale spec is worse than no spec

Probing Questions

When helping write a spec, ask:

Purpose:

  • •"If this project succeeds, what's different in the world?"
  • •"Who is the primary user/beneficiary?"
  • •"What's the one-sentence pitch?"

Scope:

  • •"What's the most common misconception about what this does?"
  • •"What adjacent problem will you NOT solve?"
  • •"If you had to cut half the features, which half stays?"

Success:

  • •"How would you demo this to prove it works?"
  • •"What would make you say 'this phase is done'?"
  • •"What metrics matter?"

Decisions:

  • •"What's the most controversial technical choice you've made?"
  • •"What would you do differently if starting over?"
  • •"What's the hardest constraint you're working with?"

See references/spec-properties.md for detailed property definitions.