Hand off in one command, pick up in one read​

specweave handoff      # in the tool you are leaving
specweave pickup       # in the next one

handoff releases your task claims, records why you stopped and what comes next, and pushes your branch and a snapshot of your uncommitted edits, so a Claude Code Projects thread, a Codex cloud task, another machine or another account can see them. pickup fetches that handoff, applies your edits and prints the increment, the next task with the text of its acceptance criteria, the branch state, the last handoff and any notes, all in one read. In a tool with SpecWeave's skills you can just say "hand off" and "pick up".

It works between Claude Code, Codex, Grok Build, Cursor, Copilot, Gemini CLI and OpenCode, and between two subscriptions of the same tool, because everything is in git.

Less for the agent to read​

• An increment is one file. spec.md holds the problem, scope, acceptance criteria, approach and tasks. tasks.md is gone for new increments, and state lives only in an append-only ledger.
• One instruction file. AGENTS.md is about 760 tokens and every tool reads it. CLAUDE.md imports it instead of repeating it; in 2.x the two together were about 3,300 tokens.
• One task at a time. task next prints the task with its criteria, so the agent stops rereading the whole spec for every task. A criterion is met when the tasks covering it are done, so nobody ticks boxes by hand.

Claude Code Projects​

A Projects thread works on one branch and opens one pull request, which is exactly an increment. So 3.0 maps them one to one: the thread's checklist is the increment's task list, threads leave each other notes in the ledger, and a committed .specweave/memory/ folder in the same format as project memory carries decisions to another account or another tool.

Nothing behind your back​

Starting, pausing or resuming an increment no longer calls GitHub, Jira or Azure DevOps, and issues are only created by specweave sync push. A third of the code, which nothing reached, is gone, along with the commands nobody called.

Upgrade​

npm install -g specweave@latest
specweave update

Existing increments keep working. What changed in 3.0 has the full list, and Handoff and pickup the details.

1,467 skills (36.82%) contained at least one security flaw. Of those, 76 contained confirmed malicious payloads — not accidental overpermissions, but deliberate credential theft, reverse shells, and data exfiltration.

What Makes Skills Dangerous​

AI agent skills are not sandboxed plugins. They are markdown files that execute with the full privileges of the host agent — filesystem access, terminal execution, network requests, and credential visibility. When you install a skill, you are handing an AI agent instructions that it will follow implicitly.

The attack surface is wide:

• Credential theft: Skills that read ~/.ssh/, ~/.aws/credentials, and crypto wallet files, then exfiltrate them via curl --data to attacker-controlled servers
• Reverse shells: Base64-obfuscated payloads piped to bash, giving attackers persistent remote access
• Memory poisoning: Skills that silently modify CLAUDE.md or MEMORY.md, injecting persistent instructions that survive across sessions
• Social engineering: Natural-language instructions like "download and run this helper tool" that trick the agent into executing malware

The Snyk study identified five named threat actors operating across multiple platforms simultaneously. This is not hypothetical — it is an active, coordinated campaign.

The Platform Problem​

Most skill platforms offer no defense. Snyk found that the majority of registries — including some of the most popular — have zero automated security scanning at the point of publication.

The ClawHub collapse illustrated the consequences. In early 2026, researchers discovered 341+ malicious skills on the platform. Five of the top seven most-downloaded skills were malware. The platform is now shut down.

Skills.sh, the most popular community registry with listings reaching 234K+ installs, has no automated scanning. Smithery learned the hard way after a path traversal vulnerability exposed data for over 3,000 MCP servers. The full platform comparison is sobering reading.

We Tested Our Scanner Against ToxicSkills​

After the Snyk study dropped, we ran SpecWeave's security scanner against samples from the snyk-labs/toxicskills-goof repository — real malicious skills collected during the research.

Tier 1 (pattern scanning) results:

Tier 1 caught 3 out of 4 samples — 75% detection through pattern matching alone, running in under 500ms per skill.

The fourth sample used pure social engineering: natural-language instructions directing users to download and run a binary from GitHub releases. No shell commands, no suspicious syntax — just "download this, extract with password, and run."

Tier 2 (LLM judge) caught it. When Tier 1 passes a skill, Tier 2 evaluates semantic intent. The LLM judge identified the social engineering pattern and flagged it as malicious.

Combined detection rate: 4/4 — 100% against the tested samples.

Three Tiers of Trust​

SpecWeave's Verified Skills Standard defines three escalating levels of certification:

1. Scanned — 52 pattern rules across 9 categories. Free. Under 500ms. Catches obfuscation, credential access, destructive commands, prompt injection, and more.
2. Verified — LLM-based semantic analysis on top of pattern scanning. ~$0.03 per skill. Catches social engineering, scope inflation, and multi-step attacks.
3. Certified — Human security review plus sandbox testing. $50-200. For high-trust, widely-used skills.

Every skill published to verified-skill.com passes at least Tier 1 before it reaches any developer. Skills that fail are rejected with detailed findings explaining exactly what was flagged and why.

The scanning methodology is fully transparent. The 52 patterns are documented. The detection categories are public. Developers can understand exactly what the scanner checks and make informed decisions about trust.

What You Should Do​

If you are using AI agent skills today:

1. Check your installed skills. Review the source of every skill you have installed. Look for shell commands, network requests, and file access patterns you did not expect.
2. Prefer verified sources. Use skills from registries that scan submissions before publication, not after (or never).
3. Run vskill scan on any community skill before installing it. The Tier 1 scanner is free and takes under a second.

The full security landscape analysis covers the threat taxonomy, platform comparison, and detailed recommendations.

The skill ecosystem is growing fast. Making sure it grows safely is not optional.

The Snyk ToxicSkills study is available at snyk.io/blog/toxicskills. SpecWeave's scanner test results are based on samples from snyk-labs/toxicskills-goof. The verified skills registry is at verified-skill.com.

Developer documentation should help people find a precise answer and help search engines identify the page that contains it. Start with useful content, clear navigation and reliable HTTP responses; then make the metadata and sitemap agree with that content.

Keep canonical URLs consistent​

Pick one public URL for each document. On SpecWeave, GitHub Pages serves directory pages with a trailing slash, so both the canonical tag and sitemap use that form. Internal links should lead directly to the current document instead of an old redirect page.

Include the preferred, indexable pages in the sitemap. Remove internal search results, reports and intentionally excluded archives. A sitemap helps discovery; it does not guarantee crawling, indexing or a particular ranking. Redirected URLs and alternate pages can be valid exclusions when they point to the right replacement. Google's canonical URL guidance explains how redirects, canonical tags and sitemap inclusion work together.

Let crawlers see a noindex directive​

An internal search page is useful navigation, but usually adds little as a search result. Give it a noindex directive and leave it crawlable:

<meta name="robots" content="noindex, follow">

Blocking that same URL in robots.txt prevents Google from reading the directive. SpecWeave's search page follows this policy and is excluded from the sitemap. Our blog tag result pages also remain intentionally excluded; original articles stay indexable. Use exclusions deliberately rather than treating every Search Console notice as a bug. See Google's noindex documentation.

Describe the page people will read​

Give each page a clear title and a relevant description. An integrations overview and a CLI reference should have distinct titles even when they share a broad topic. Archive pages need descriptions too: identify the author or topic and explain what readers can find there.

Use the words developers use when asking the question, in readable headings, link text and content. A keywords meta tag does not affect Google's indexing or ranking. Social cards help people recognize shared links, but they do not establish a fixed search click-through improvement. Google's SEO Starter Guide describes these practices and their limits.

Publish truthful structured data​

Structured data can describe the organization and software application. Keep its URL, license, price and supported platforms consistent with the product. Do not invent ratings, reviews or measured outcomes to qualify for a search feature.

Valid Schema.org markup and eligibility for a Google rich result are separate checks. Google's software app feature requires a real rating or review as well as the other required properties. Our application description does not claim that result. Validate supported markup and inspect the deployed page. Google's software application documentation lists the requirements.

Verify delivery, then measure discovery​

Before publishing, inspect the rendered HTML, follow internal links and test the sitemap against the built pages. Check that missing pages return HTTP 404, indexable pages have one matching canonical, and deliberately excluded pages stay out of the sitemap. Test narrow screens, readable themes and image loading as part of the same release.

After deployment, repeat the public checks and use Search Console to monitor impressions, clicks, queries and indexing over time. A successful build or Lighthouse score proves a specific technical check, not an organic traffic increase. Keep the measured baseline, date range and changes together before attributing a result to SEO work.

Explore the SpecWeave introduction or start in your project.

The Problem: Vibe Coding Doesn't Scale​

Traditional development with AI assistants suffers from:

• ❌ No source of truth - Specifications drift from implementation
• ❌ Context overload - Loading entire codebases wastes tokens
• ❌ Brownfield chaos - Modifying existing code causes regressions
• ❌ Tech stack assumptions - Tools assume Next.js, ignore Python/Go
• ❌ Documentation debt - Docs become outdated immediately

The Solution: SpecWeave​

SpecWeave is a specification-first AI development framework where:

✅ Specifications are SOURCE OF TRUTH - Code expresses specs in a language ✅ Context Precision - Load only what's needed (70%+ token reduction) ✅ Regression Prevention - Baseline tests + context-aware planning (brownfield-ready) ✅ Framework-Agnostic - Works with ANY tech stack (TypeScript, Python, Go, Rust, Java) ✅ Living Documentation - Auto-updates via Claude Code hooks ✅ Test-Validated - E2E tests ensure features work (closed-loop validation)

Key Features​

1. Framework-Agnostic Commands​

specweave init --type python --framework fastapi
sw:increment "user authentication"
sw:progress

Commands detect your tech stack and adapt automatically.

2. Selective Agent Installation​

Install ONLY the agents you need:

# Python API project: 7 agents (1,050 tokens)
npx specweave install --detect

# vs Loading ALL 19 agents (2,600 tokens) ❌

60% token reduction on agents!

3. Progressive Disclosure​

# Claude's native progressive disclosure - no infrastructure needed
# SKILL.md metadata loads first (~75 tokens per skill)
# Full content loads only when relevant

# Example: Search living docs for context
grep -ril "auth" .specweave/docs/internal/
# → Finds specs, ADRs, architecture docs
# → Claude reads exactly what's needed

Load exactly what's needed - 70%+ token savings with zero infrastructure.

4. Increment Lifecycle​

backlog → planned → in-progress → completed → closed

Track features with WIP limits, transfer leftovers, maintain focus.

5. Flexible Documentation​

Supports BOTH approaches:

• Enterprise: Comprehensive upfront (500-600+ pages)
• Startup: Incremental/evolutionary (build as you go)

Tech Stack Support​

SpecWeave works with ANY language/framework:

Getting Started​

# Install SpecWeave
npx specweave init

# Create your first project
specweave init --type python --framework fastapi

# Start building
sw:increment "user authentication"

What's Next?​

• 🔧 Integration Agents - JIRA, Azure DevOps, GitHub sync
• 📊 Diagram Agents - C4 diagrams, sequence diagrams
• 🎨 Figma Integration - Design to code workflow
• 🧪 Test Import - Import existing tests to SpecWeave
• 🚀 Deployment Intelligence - Cost optimization, Hetzner/AWS/Railway

Learn More​

• Documentation
• GitHub Repository
• Quick Start Guide

Join the revolution. Build production software with confidence, clarity, and continuous validation.

⭐ Star us on GitHub if you like SpecWeave!