Skip to content
Back to skills

Tech Spec

ASecurity

Produces implementation-ready technical specifications with concrete contracts, module boundaries, data flows, file changes, and test slices. Use for architecture or implementation handoffs.

  • 5 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added September 10, 2026
ai-agentsgotestingapi

Works with

  • api

Security analysis

A100/100

Scanned September 10, 2026

npx -y skills add iurysza/agent-skills --skill tech-spec --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Tech Spec?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Tech Spec
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/iurysza-tech-spec/badge)](https://www.skillsdirectory.com/skills/iurysza-tech-spec)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: tech-spec
description: Produces implementation-ready technical specifications with concrete contracts, module boundaries, data flows, file changes, and test slices. Use for architecture or implementation handoffs.
metadata:
  category: planning-architecture
---

# Technical Specification

A tech spec is a typed architecture handoff. Types and call stacks define what changes; prose explains why.

This workflow is design-only. Do not implement. Write durable specs to `ai-artifacts/specs/YYYY-MM-DD-<topic>.md` unless the user or repository explicitly requires another location.

## Choose the path

- **Convert context:** use when conversation, docs, and code already define the problem and constraints.
- **Set up the goal first:** use the `setup-goal` skill when important requirements, boundaries, or acceptance criteria remain unresolved.

Answer repository questions by inspecting the repository. Ask the user only for decisions.

## Build the spec

### 1. Establish current state

Read relevant code, tests, docs, project instructions, domain vocabulary, and architectural decisions. Trace the existing entrypoint-to-effect flow.

Capture the problem, callers, goals, non-goals, constraints, invariants, affected systems, operational concerns, risks, and open questions. Do not invent missing requirements.

### 2. Compare real alternatives

Offer materially different designs. They should differ in ownership, interfaces, seam placement, call stack, runtime topology, or state model—not merely names.

For each option show:

- domain and application types
- public interfaces
- module and adapter ownership
- entrypoint-to-effect call stack
- failure and cancellation behavior
- persistence and transaction boundaries
- testing seams
- costs and risks

Choose the recommendation only after comparison.

### 3. Define contracts

Sketch every new or changed boundary in code:

```ts
type Input = { /* parsed application values */ };
type Output = { /* caller-visible result */ };
type ExpectedFailure = FailureA | FailureB;

interface Capability {
  execute(input: Input): Promise<Result<Output, ExpectedFailure>>;
}
```

Cover domain values, state variants, request/response shapes, parsers, functions, ports, adapters, records, events, and public APIs as applicable. State what may cross each boundary and what must remain private.

### 4. Trace behavior end to end

For every affected behavior, show the call and data flow:

```text
raw input
  -> protocol parser
  -> application/domain input
  -> service or domain operation
  -> outbound port
  -> adapter and external effect
  -> typed result or failure
  -> protocol projection
```

Include old versus proposed flow when changing an existing path. Add authorization, retries, cancellation, idempotency, transactions, observability, and runtime hops when reachable.

### 5. Map files

List files to add, change, and delete. Give each file one clear responsibility tied to a contract or call-stack step.

### 6. Plan vertical test slices

Use red-green cycles, one behavior at a time:

1. agree on the public seam;
2. add one failing behavior test;
3. write the minimum implementation to pass;
4. repeat with the next behavior.

Cover happy paths, important failures, parser rejection, domain invariants, adapter contracts, persistence/runtime semantics, and end-to-end high-consequence flows. Avoid a horizontal “all tests, then all code” plan.

## Required outline

```markdown
# Title

## Summary
## Current State
## Goals
## Non-Goals
## Invariants and Constraints
## Alternatives
## Recommendation
## Domain Model and Types
## Interfaces and APIs
## Boundaries and Adapters
## Call Stacks and Data Flow
## Files to Add, Change, or Delete
## Red-Green Test Plan
## Risks and Open Questions
```

Compress sections that do not apply, but never omit changed contracts, call stacks, seams, or tests merely because they are difficult to specify.

## Completion criteria

- every requirement is grounded or marked open
- alternatives are materially different
- each changed boundary has a concrete contract
- each behavior has an end-to-end call stack
- each contract maps to a file or open question
- the test plan proceeds in vertical red-green slices
- another engineer can implement without guessing architecture

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.