SpecWeave

The Secure Skill Factory Standard is an RFC (Request for Comments) defining how AI agent skills, authored as SKILL.md files, should be authored, verified, and distributed. It aims to mitigate security risks such as malicious payloads, credential exfiltration, and prompt injection by establishing a minimum safety bar for the skills ecosystem.

The standard introduces five key mechanisms:

1. Mandatory SKILL.md sections: Ensures skill behavior is transparent and auditable.
2. Forbidden patterns: Defines behaviors that lead to automatic disqualification from certification.
3. Security prompt templates: Allows compliant skills to embed declared safe boundaries.
4. Three-tier certification: Provides graduated trust levels: Scanned, Verified, and Certified.
5. Trust labels: Communicates skill quality, compatibility, and status to users.

Backend development (server-side development) focuses on the logic, data management, and security that occur behind the user interface. While the frontend handles presentation and interactivity in the browser, the backend runs on servers to ensure data integrity and coordinate with external services.

Core Backend Responsibilities:

• Process HTTP requests: Handle incoming API calls from clients.
• Manage data: Perform CRUD (Create, Read, Update, Delete) operations in databases.
• Enforce business logic: Apply application-specific rules (e.g., validation, constraints).
• Authenticate users: Verify identities and manage sessions.
• Integrate services: Connect to third-party APIs (e.g., payments, email).
• Run background jobs: Execute time-consuming tasks asynchronously.

The AI agent skills ecosystem (markdown files instructing agent behavior) is a significant attack surface for supply chain compromises, credential theft, and prompt injection. Because skills are easy to install, they are easily weaponized.

Key security risks include:

• Prompt Injection: Malicious instructions that bypass model safeguards.
• Credential Theft: Skills designed to exfiltrate API keys or user data.
• Data Exfiltration: Unauthorized transfer of sensitive information.
• Supply Chain Attacks: Compromising the registry or the skill distribution process.
• Privilege Escalation: Using memory poisoning to gain unauthorized access.

Developers should be aware that many community platforms offer little to no automated scanning, placing the burden of security on the user to manually inspect skill source files before installation.

SpecWeave provides a structured development loop that ensures AI-generated code is traceable, tested, and documented. Key capabilities include:

SpecWeave is built as a bundled plugin containing several layers of automation:

• Bundled Plugin: The core container providing lifecycles for Incrementing, GitHub/JIRA/ADO syncing, Testing/TDD, Code Review, Release Management, Documentation, Diagrams, and Team Orchestration.
• Skills (44 total): Auto-activate based on keywords to provide domain expertise.
• Commands (72 total): User-invoked slash commands for explicit actions.
• Agents (24 total): Comprised of 3 top-level agents and 21 sub-agents for task execution.
• Hybrid Hooks:
  • Global Hooks: Defined in hooks.json, these are cross-cutting (e.g., start, stop, prompt).
  • Skill-scoped Hooks: Defined in frontmatter, these are command-specific and only fire when the associated skill is active.

Future updates to the contradiction resolution system are planned to include:

• LLM-assisted detection: Integrating an LLM judge (using skill-judge.ts) to evaluate borderline conflicts that keyword matching cannot resolve.
• Community resolution database: A mechanism for developers to share and access practical resolutions for specific conflicts.
• Automatic scoping: Automatically scoping conflict resolutions to specific directories (e.g., /app/legacy/) if the conflicting skills are scoped to those areas, rather than applying resolutions project-wide.
• Continuous monitoring: Re-running contradiction detection whenever skills are updated and notifying developers of new conflicts within their installed skill set.

The specweave (aliased as sw) plugin manages the full development increment lifecycle: plan → work the ledger → verify → review → complete. It handles cross-tool handoffs and synchronization with trackers like GitHub, Jira, and ADO.

Note: In version 2.x, the commands/ namespace has been removed. Deterministic operations are now handled via specweave CLI subcommands, and model-judgement procedures are handled via the 10 core skills.

A Skill is a SKILL.md file containing structured instructions that package domain knowledge (patterns, rules, and examples). Unlike a standard prompt, a skill is:

• Reusable: Invoked by name (e.g., sw:review) rather than copy-pasted.
• Extensible: You can override behavior using skill-memories/ without modifying the original source.
• Composable: Skills can invoke other skills (e.g., a PM skill triggering an Architect skill).
• Stateful: It learns from corrections permanently.
• Testable: Uses quality gates to verify output automatically.

When you define a skill, Claude adds it to its toolkit and uses it automatically when relevant, or you can invoke it directly using the /skill-name syntax.

A Skill is a formalized unit of domain expertise represented by a SKILL.md file. It injects specific patterns, rules, and examples into an AI's context to transform generic LLM output into production-grade, domain-specific results.

Invocation Methods

You can invoke a skill in three ways:

1. Natural Language: Using descriptive prompts (e.g., "design the architecture").
2. Slash Commands: Using SpecWeave-specific commands (e.g., sw:increment).
3. CLI Keywords: Using keywords in other AI tools (e.g., architect).

SpecWeave is a batteries-included development platform that provides 45 skills, 73 commands, and 3 AI agents out of the box.

AI Agents

Agents are specialized AI personas that collaborate during the planning phase:

• PM: Writes spec.md containing user stories and acceptance criteria.
• Architect: Writes plan.md containing architecture decisions and component design.
• Planner: Generates tasks.md with BDD (Behavior Driven Development) test plans using Given/When/Then syntax.

Skills vs. Commands

• Skills: High-level capabilities that users interact with directly (e.g., tdd-cycle, code-reviewer, jira-sync).
• Commands: Low-level operations (e.g., github-push, jira-pull) that are invoked by skills or sync workflows behind the scenes.

Living Documentation is a core SpecWeave concept where documentation stays automatically synchronized with your codebase and project state. Unlike static documentation, living docs are maintained through three primary mechanisms:

1. Auto-Update After Tasks: SpecWeave uses a post-task-completion hook that triggers automatically when a task is finished, syncing documentation in the background without manual intervention.
2. Bidirectional Sync: Changes flow between your local .specweave/ directory and external systems like GitHub, JIRA, or ADO. For example, completing a task in SpecWeave can update a GitHub issue, and closing a GitHub issue can update a SpecWeave increment.
3. Validation: Every sync includes automated validation checks for AC-ID (Acceptance Criteria ID) coverage, test coverage targets (typically 85-90%), link integrity, and correct content classification.