skills.rest
alvis
alvisCOMMUNITY
Explore all skills by this author →
Website𝕏@alvishttangGitHub

spec-code

Author and update technical specifications from local, inline, or Notion sources with provenance tracking.

4|1|Updated Jul 31, 2025
Search Tags:#documentation#specification#technical design#provenance#notion#codebase analysis#contract
One-click install
npx skills add https://github.com/alvis/.agents --skill spec-code-alvis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec-code
Source: https://github.com/alvis/.agents/tree/main/plugins/specification/skills/spec-code
Command: npx skills add https://github.com/alvis/.agents --skill spec-code-alvis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Technical specifications drift out of sync with code and decisions, and teams lose track of which version of a spec was actually approved. This Skill designs, updates, or retrospectively documents a technical specification as one coherent contract, binding approvals to exact content and recording provenance for every derived artifact. ## Core Features & Use Cases - Three authoring modes: CREATE a new specification, UPDATE an existing one, or DOCUMENT an existing codebase retrospectively by extracting architecture, APIs, and components from actual code. - Multi-source support: Works with explicit local file paths, inline prompt requirements (via an approved work-local candidate), or Notion-backed sources with transport synchronization. - Provenance receipts: Writes spec/README.md plus a machine-readable spec/provenance.json recording source locators, template identity, content hashes, and logical-unit mappings. - Use Case: Point it at an existing Express codebase with --capability=express-api and it extracts the tech stack, routes, and components into a structured capability specification without inventing requirements. ## Quick Start Ask the agent to document the existing codebase into a capability specification using spec-code with a chosen capability slug such as --capability=express-api.

Frequently Asked Questions about spec-code

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a technical specification from an existing codebase?▼

Use DOCUMENT mode by invoking spec-code with a capability slug, for example documenting an Express API. It scans the project structure, extracts the tech stack from package.json, maps architecture and API endpoints from code, and fills the specification template with actual implementation details.

What sources can a specification be authored from?▼

Three source kinds are supported: an explicit local file path, inline prompt text treated as requirements evidence, or a selected Notion page. Inline text must first become an approved work-local candidate before it can serve as the authoritative contract.

Does spec-code support Notion synchronization?▼

Yes, when a Notion source or destination is explicitly selected. Notion transport is delegated to sync-notion and sync-spec capabilities, requires an explicit --body-author capability for body edits, and keeps canonical URLs and revisions as the external authority.

What is the difference between CREATE, UPDATE, and DOCUMENT modes?▼

CREATE authors a specification when none exists, UPDATE modifies an existing authoritative specification, and DOCUMENT describes current code without inventing requirements. All modes integrate edits into owning sections rather than appending addenda.

Where does the approved specification content live?▼

Approved specification content is materialized into the active work's spec/ directory, with spec/README.md as the readable contract and spec/provenance.json as the machine-readable receipt. Root-level specification artifacts are never created.

Why does spec-code require explicit approval of specification content?▼

Approvals bind to the exact specification content, so any semantic edit invalidates the prior approval and requires re-approval. This prevents stale approvals from being applied to changed contracts and keeps planning and implementation anchored to verified content.

Related Skills

Explore More Software Engineering Skills→
srstompsrstomp
8

deep-research

Coordinate multi-day technology research into stakeholder-ready reports with structured templates.

Community
Advanced
dailydmdailydm

implement

Translate breakdown tasks into implementation plans and code changes.

Community
Advanced
mikestopcontinuesmikestopcontinues

grill-me

Conducts a Socratic interview to resolve open design decisions one question at a time.

Community
Intermediate
phrazzldphrazzld

documentation-standards

Enforce rationale-based comments and structured project documentation standards.

Community
Basic