SkillAgentSearch skills...

spec-workflow

Use when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests.

Install / Use

npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill spec-workflow

Installs into whichever agent you are using.

About this skill
πŸ“„

SKILL.md

Installable skill definition

Quality Score

87/100

Category

Automation

Supported Platforms

Universal

Our assessment of spec-workflow

spec-workflow scores 87/100 on our quality scale, 1691st of 2,769 Automation skills we index.

Its SKILL.md is 5.0 KB long, well organised into 21 sections with 3 code examples: a solid amount of guidance for an agent.

With 1,124 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
26/30
Structure
18/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so spec-workflow is actively maintained.
  • Our last check on 2026-11-02 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit β€” read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk β€” read a skill before letting an agent act on it.

spec-workflow compared with similar skills

All 4 of these similar skills score higher than spec-workflow; compare them before choosing.

SkillScoreStarsUpdatedFormat
spec-workflow (this skill)by TencentCloudBase871.1k54d agoSKILL.md
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
Agent-Reachby Panniantong100112.7k9d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.9k8d agoCLAUDE.md

Frequently asked questions

How do I install spec-workflow?
Run npx skills add TencentCloudBase/CloudBase-AI-Toolkit --skill spec-workflow. The install tabs above show the steps for each supported agent.
Which AI agents does spec-workflow work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is spec-workflow safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is spec-workflow still maintained?
The repository was last updated about 2 months ago, so spec-workflow is actively maintained.

name: spec-workflow description: Use when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests. version: 2.34.8 alwaysApply: false

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Spec Workflow

Activation Contract

Use this first when

  • The request is a new feature, multi-step product change, cross-module integration, or architecture/design task.
  • Acceptance criteria are unclear and need to be made explicit before implementation.
  • The work involves multiple files, user flows, database design, or UI design that needs staged confirmation.

Read before writing code if

  • You are unsure whether the task should go straight to coding or should first go through requirements, design, and task planning.
  • The request mentions a new page, a new system, a redesign, a workflow, or a multi-module refactor.

Then also read

  • Frontend page or visual design work -> ../ui-design/SKILL.md
  • Advanced data-model work -> ../data-model-creation/SKILL.md

Do NOT use for

  • Small bug fixes with clear scope.
  • One-file documentation updates.
  • Straightforward config changes.
  • Tiny refactors where the user already gave exact implementation instructions.

Common mistakes / gotchas

  • Jumping into coding before acceptance criteria are explicit.
  • Skipping user confirmation between requirements, design, and tasks.
  • Writing vague tasks that do not map back to user-visible outcomes.
  • Treating UI work as purely technical implementation without clarifying design intent.

Minimal checklist

  • Decide whether the change really needs the full spec flow.
  • If yes, stop and produce requirements first.
  • If the change is small, low-risk, and acceptance is already clear, allow direct execution without forcing spec artifacts.
  • Use EARS-style acceptance criteria.
  • Get confirmation before moving to the next phase.

When to use this skill

Use this workflow for structured development when you need to:

  • Define or refine a new feature
  • Design complex architecture
  • Coordinate changes across modules
  • Plan database or UI-heavy work
  • Improve requirement quality and acceptance boundaries

Decision rule

Use the full workflow when

  • The task is medium or large
  • The impact spans multiple modules
  • Acceptance boundaries are fuzzy
  • The user wants disciplined planning before implementation

Skip the full workflow when

  • The task is small, low-risk, and already precise
  • Goal, scope, and acceptance are already clear enough to execute directly
  • The user explicitly wants a direct code change with no planning phase

Core workflow

Phase 1: Requirements

Create specs/<spec_name>/requirements.md.

What to do:

  • Restate the problem and scope
  • Write user stories
  • Write acceptance criteria in EARS style
  • Clarify business rules, constraints, and non-goals

EARS pattern:

While <optional precondition>, when <optional trigger>, the <system name> shall <system response>

Example:

When the user submits the form, the booking system shall validate required fields before creating the record.

Phase 2: Design

Create specs/<spec_name>/design.md.

What to do:

  • Describe architecture and module boundaries
  • Explain technology choices and trade-offs
  • Define data model, API, security, and testing strategy as needed
  • Use Mermaid only when a diagram materially improves clarity

Phase 3: Tasks

Create specs/<spec_name>/tasks.md.

What to do:

  • Break the design into executable tasks
  • Keep tasks specific and reviewable
  • Link each task back to the relevant requirement
  • Update task status as work progresses

Task format:

# Implementation Plan

- [ ] 1. Task title
  - Specific work item
  - Another concrete step
  - _Requirement: 1

Phase 4: Execution

Only start implementation after the user confirms the task plan.

During execution:

  • Keep task status current
  • Finish one meaningful unit at a time
  • Preserve traceability from change -> task -> requirement

Working rules for the agent

  1. Ask follow-up questions when the request is underspecified; do not guess core product behavior.
  2. Require confirmation between requirements, design, and task breakdown.
  3. Pull in ui-design early when the change includes end-user pages or visual decisions.
  4. Keep documents concise but testable.
  5. Prefer user-visible outcomes over implementation-detail task names.

Output expectations

  • requirements.md -> problem, scope, user stories, EARS acceptance criteria
  • design.md -> architecture, technical approach, data/API/security/test notes
  • tasks.md -> actionable implementation checklist tied to requirements

Related Skills

View on GitHub
GitHub Stars1.1k
CategoryAutomation
Updated1mo ago
Forks143

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit β€” see the Safety scan above for what the skill file itself contains.

No cautions
spec-workflow β€” Universal Skill: Install & Safety Check | SkillAgent