Spec Driven
An orchestrator-first collection of Agent Skills for spec-driven development: the orchestrator skill turns a PRD or idea into approved SPECs, tracked GitHub Issues, TDD-implemented slices, QA gates, and reviewed PRs — across Claude Code, OpenCode, Devin, Cursor, and other runtimes.
🚀 Overview
This repository implements Spec-Driven Development (SDD) for AI agents, following the Agent Skills Specification (agentskills.io). At the center is the orchestrator skill: a control loop that audits preconditions, provisions the agent harness, consolidates domain language into approved SPEC SDDs (.specs/SPEC-*.md), fragments work into GitHub Issues, and delegates implementation, review, QA, and documentation to specialized skills — never doing complex work itself.
Every other skill in the catalog is a delegation target in that loop. Instead of generic prompts, each skill provides structured patterns, constraints, and reference materials that allow agents to perform complex software engineering tasks with production-grade quality.
🧭 The Orchestrator
The orchestrator is the entry point and central control skill for agent-driven projects. Invoke it with /spec-driven (alias for /spec-driven:orchestrator, or "use the orchestrator skill") and it runs a continuous loop, delegating complex work to specialized skills and persisting state in .claude/memory/orchestrator_stats.md.
flowchart TD
A[Phase -1: Framework Update] --> B[Phase 0: Governance]
B --> C[Phase 1: Discovery]
C --> D[Phase 2: Audit]
D --> E[Phase 3: GitHub Fragmentation]
E --> F[Phase 4: Implementation Loop]
F --> G[Phase 5: Verification & QA]
G --> H[PR / Merge]
C -->|PRD only| I[/scaffold-mvp\]
C -->|needs spec| J[/write-specs\]
D -->|P2 gap| K[/improve-codebase-architecture\]
E --> L[/create-issues\]
F -->|per slice| M[/execute-specs\]
F -->|bug| N[/diagnose\]
G --> O[/qa-analyst\]
G --> P[/architecture\]
G --> R[/gap-analysis\]
S[/migration-planner\] -.->|domain plans| J
T[/web-design-guidelines\] -.->|finding groups| J
The orchestrator advances automatically between phases once validation passes. It only pauses for escalation gates (security, schema, public APIs, data changes), validation failures, or an explicit user request to stop.
🛠️ Skill Catalog & Correlation
The skills are organized around the orchestrator's pipeline: Harness Engineering, Orchestration & Delivery, Code Quality & Review, Frontend & Design, Extensibility & Integration, and MCP Integrations.
🏗️ Harness Engineering
Foundation for creating and managing AI agents.
create-agent-harness: The starting point. Use this to bootstrap a complete agent environment (CLAUDE.md, rules, skills) in any repo.create-readme: Professionalizes the repository landing page. Generates evidence-based READMEs and SemVer-compliant CHANGELOGs.observability-and-instrumentation: Once the harness is set, use this to ensure the agent's actions and the application's behavior are visible and diagnosable in production.
🧭 Orchestration & Delivery
Planning, execution, verification, and documentation for agent-driven projects.
orchestrator: Central control skill. Audits preconditions, creates documentation, reconciles open GitHub Issues, turns gaps into Issues, and coordinates execution, tests, QA, and PR in a continuous loop. Persists state in.claude/memory/orchestrator_stats.mdand auto-continues to the next slice.write-specs: Interviews the user in Portuguese to consolidate domain language and produce an approved.specs/SPEC-{YYYYMMDD}-{feature}.mdbefore implementation.scaffold-mvp: Bootstraps a new .NET/Blazor/Angular repository after domain/spec alignment. Installs the agent harness, proposes a productive stack, and generates the initial project skeleton, AD-0001, and stubs.create-issues: Turns approved gaps, roadmap, and specs into GitHub Issues with vertical slices and dependency links. Uses thereferences/spec-sdd-template.mdstructure when creating Issues from SPEC SDDs.execute-specs: Test-driven development using the approved SPEC SDD as the source of truth. Red-green-refactor one vertical slice at a time.qa-analyst: Full QA cycle — requirements analysis, test planning, test cases, execution, bug reports, and process improvement.diagnose: Disciplined diagnosis and re-validation loop for hard bugs and performance regressions — tight feedback loops, ranked falsifiable hypotheses, stack playbooks for .NET/Angular/Python/React, agent self-debug, and AI workflow audit.improve-codebase-architecture: Finds architectural deepening opportunities by reading.claude/CONTEXT.md,.claude/MEMORY.md, anddocs/architecture/, and produces an HTML report.
💎 Code Quality & Review
Ensuring the output meets professional standards.
code-review-and-quality: The primary gatekeeper. Performs multi-axis reviews (correctness, security, performance) before any code is merged.quality-test-implementation: The whole-repo quality intervention. Fixes static-analysis warnings (Roslyn/Sonar, SpotBugs/Checkstyle, Bandit/Ruff), resolves security CVEs, and applies SOLID/DDD/Clean Architecture across .NET, Java, or Python repositories.sonarqube-autofix: The automated auditor. Integrates with SonarQube to identify and fix technical debt and smells systematically.
🔬 Security & Reverse Engineering
Authorized analysis of shipped artifacts, protocols, and adversarial surfaces.
reverse-engineer: Consolidated RE hub merging REA (rea-agentsCLI/MCP, evidence-ledger workflows) with the reverse-skill domain pack — 40+ guides covering binaries, APK/mobile, JS/Electron, .NET, firmware, protocols, malware, CTF, and authorized pentest lanes. Includes a deterministic router (master-route.sh), case/scope gates (case-init.sh,auth.status=grantedrequired before ACT), a per-module tool-readiness checker (check-tools.sh), and an REA installer (install-rea.sh).
🎨 Frontend & Design
Shaping user-facing interfaces with mobile-first, responsive craft.
design: Frontend UI design for Angular, React, and Blazor. Covers mobile-first responsive layouts, typography, color, components, accessibility, motion, design tokens, Bootstrap/Tailwind CSS examples, and production hardening.web-design-guidelines: Web design validation, merged from vercel-labs/web-design-guidelines + lighthouse-95. Audits UI files against the complete interface-guidelines rule set (file:linefindings, with Angular/Blazor mappings) and/or verifies deployed pages against Lighthouse 95+ (mobile + desktop, 3-run verdicts), then converts confirmed pendencies into Draft SPECs (write-specs), an Epic + Issues (create-issues), and orchestrated fixes (orchestrator).
🔌 Extensibility & Integration
Expanding what the agent can actually do.
building-mcp-servers: The power-user tool. Teaches agents how to build their own Model Context Protocol (MCP) servers to connect to any API or database.drawio-architecture: Visual intelligence. Merges architecture diagram authoring with the official draw.io MCP server for automated system design.mermaid-architecture: Diagrams as code. Generates high-contrast, production-ready Mermaid architecture diagrams, workflows, and C4 models saved directly indocs/architecture/.obsidian: Obsidian vault operations. Runs the Obsidian CLI (read/create/search/manage notes, tasks, properties), builds Bases (.base views/filters/formulas), writes Obsidian Flavored Markdown (wikilinks, embeds, callouts), and develops/debugs plugins and themes.
🔗 MCP Integrations
Configuring, authenticating, and using external MCP servers across all supported agent platforms.
composio-mcp: Connects AI agents to 1000+ external apps (Gmail, GitHub, Slack, Notion, Linear, Jira) via Composio. CLI-first path (ak_*project key) with MCP fallback (ck_*consumer key viax-consumer-api-keyheader). Includes multi-platform setup script (handlesserverUrlvsurl,mcpvsmcpServers,environmentvsenvacross Claude Code/Desktop, Cursor, Devin CLI/Desktop, OpenCode, Antigravity IDE/CLI, OpenClaw), verify script, per-platform config reference, and cross-platform quirks matrix.notebooklm-mcp: Google NotebookLM (Gemini Notebook) integration via thenlmCLI andnotebooklm-mcpserver. Desktopnlm loginis the default auth path; headless fallbacks (OpenClaw CDP or user-provided manualcookies.txt) require explicit user approval. Credentials/cookies are never logged, copied, or forwarded. Multi-platform setup script covering all 8 supported agent platforms, plus verify, auth guide, per-platform config reference, and cross-platform quirks matrix.wordpress-mcp: Expose WordPress to AI agents over MCP using pinned, verified plugins. Three paths: (A)wordpress/mcp-adapterofficial plugin from GitHub releases, (B) AI Engine plugin from wordpress.org, and (C) wp-mcp-ultimate (community, opt-in, requires explicit source review and user approval). High-privilege actions require explicit approval; WordPress posts/comments/user submissions are treated as untrusted data. Includes hardened WP-CLI install scripts with checksum support, Application Password / Bearer Token / OAuth setup, per-platform MCP config, endpoint verification, and troubleshooting.
📚 Documentation: each skill has a dedicated doc page in
docs/en/(English) anddocs/pt-br/(Português).
🛡️ Security Audits
Latest results from the skills.sh third-party audit (Gen Agent Trust Hub, Socket, Snyk). Click View to see the full report for a skill.
Updated: 2026-10-08
Mitigations applied (PR #11):
notebooklm-mcp,orchestrator, andwordpress-mcpwere hardened with explicit-approval gates, pinned installs, credential isolation, untrusted-content handling, and audit logging. The latest scan still flagsarchitecture,notebooklm-mcp, andwordpress-mcpas 🟡 medium risk on Gen Agent Trust Hub, andnotebooklm-mcpandsonarqube-autofixeach carry 1 Socket alert.
📦 Installation
⚡ via skills.sh (Recommended)
The fastest way to install and auto-detect your environment.
npx skills add afonsoft/skills
🧩 via Claude Code plugin
Installs skills and slash commands natively (no install.sh needed):
/plugin marketplace add afonsoft/skills
/plugin install spec-driven@afonsoft
Commands are namespaced by the plugin name: /spec-driven:orchestrator and /spec-driven:<skill> for each skill.
🤖 via Codex plugin marketplace
The repo ships a Codex plugin manifest (.codex-plugin/plugin.json) and a repo marketplace catalog (.agents/plugins/marketplace.json):
codex plugin marketplace add afonsoft/skills
Then install spec-driven from the Plugins Directory, or invoke skills directly with $<skill> — Codex discovers them from the bundled skills/ directory. Skills are also discovered from .agents/skills/ (repo scope) and ~/.agents/skills/ (user scope, via install.sh --codex).
🌐 via OpenCode HTTP catalog
Add the catalog URL to any opencode.json — OpenCode downloads skills/index.json and refreshes each skill automatically when its version changes:
{
"$schema": "https://opencode.ai/config.json",
"skills": ["https://raw.githubusercontent.com/afonsoft/skills/main/skills/"]
}
Regenerate the catalog after skill changes with python3 scripts/build-opencode-catalog.py. OpenCode also discovers skills from .opencode/skills/, .claude/skills/, and .agents/skills/ in project scope.
🖥️ via install.sh (local clone)
Copies the skills into each IDE's skills directory and generates slash commands:
./install.sh --all # all supported IDEs/CLIs + slash commands
./install.sh --claude # Claude Code only
./install.sh --opencode # OpenCode only
./install.sh --devin # Devin Desktop + Devin CLI
./install.sh --cursor # Cursor only
./install.sh --codex # OpenAI Codex CLI only
./install.sh --agy # Google Antigravity CLI only
./install.sh --aider # Aider only
./install.sh --cline # Cline only
./install.sh --continue # Continue only
./install.sh --grok # Grok CLI only
./install.sh --kimi # Kimi Code CLI only
./install.sh --kiro # Kiro CLI only
./install.sh --qwen # Qwen Code only
./install.sh --dry-run # preview without changing anything
Slash commands follow each CLI's own convention — some clients do not accept : in command names:
Reinstalling removes legacy /architecture:<skill> shims automatically.
📣 Publish on Skill Directories
SkillsLLM
SkillsLLM indexes open-source skills for Claude Code, Codex CLI, and ChatGPT. The scraper discovers repos daily via GitHub topics (claude-code, ai-agent, mcp-server, agent-skills, skill-md) and SKILL.md files. To list this collection:
- Sign in with GitHub at Submit a Skill
- Submit the repository URL:
https://github.com/afonsoft/skills - The scraper validates, fetches metadata, runs a security scan (Semgrep + npm audit + pip-audit), and adds it to the catalog within 24 hours
Note: SkillsLLM's automated discovery filters for repos with 100+ stars. Manual submission via the form above bypasses that filter — the repo is then scanned and listed regardless of star count. The GitHub topics and description are already set so the scraper can categorize the skills correctly.
Awesome Skills
Awesome Skills discovers open-source SKILL.md skills from GitHub via its Awesome List Import. Each skills/<name>/SKILL.md directory becomes a separate listing with slug afonsoft-skills-<name>. Submit the repository URL through the site's Submit a Skill form:
- Repository URL:
https://github.com/afonsoft/skills - Branch:
main - Skills Path:
/skills
Each skill's description frontmatter includes afonsoft so the collection is discoverable at awesomeskill.ai/search?q=afonsoft. The Awesome Skills search API matches against skill name and description only (not owner, repo, or tags), so the afonsoft attribution in each description is what makes the search return results.
SkillHub
SkillHub aggregates skills from GitHub sources. Open Sources → Add Source, then use:
- Name:
afonsoft/skills - Repository URL:
https://github.com/afonsoft/skills - Source Type:
GitHub Repo - Branch:
main - Skills Path:
/skills
SkillHub imports the collection from this source and lists each valid SKILL.md directory in its marketplace.
LobeHub Skills Marketplace
LobeHub is the world's largest skills marketplace (100,000+ skills). Publishing is CLI-driven (no web form). Each skill gets identifier afonsoft-skills-<name>.
One-time setup (per machine, requires Node.js >= 22):
npx -y @lobehub/market-cli login # browser OAuth
npx -y @lobehub/market-cli github connect # verify GitHub ownership
Publish all skills locally:
./publish-lobehub.sh # publishes all skills
./publish-lobehub.sh --dry-run # preview without publishing
Publish a single skill:
npx -y @lobehub/market-cli skill publish --dir skills/<skill-name> --identifier afonsoft-skills-<skill-name>
Automatic publishing via GitHub Actions:
A workflow (.github/workflows/lobehub-publish.yml) publishes all skills when a v* tag is pushed, a release is published, or when triggered manually (workflow_dispatch). To enable it, add two repository secrets:
LOBEHUB_M2M_CREDENTIALS— contents of~/.lobehub-market/credentials.json(device registration)LOBEHUB_USER_CREDENTIALS— contents of~/.lobehub-market/user-credentials.json(OAuth tokens)
# After running lhm login + lhm github connect locally:
gh secret set LOBEHUB_M2M_CREDENTIALS < ~/.lobehub-market/credentials.json
gh secret set LOBEHUB_USER_CREDENTIALS < ~/.lobehub-market/user-credentials.json
The workflow restores both credential files, verifies auth, then runs ./publish-lobehub.sh. The refresh token auto-renews the access token, so the workflow stays authenticated across runs.
After publishing, skills appear at market.lobehub.com/s/skills/afonsoft-skills-<name> and are searchable at lobehub.com/skills?q=afonsoft.
ClawHub
ClawHub is the public skill registry for OpenClaw. Each skills/<name>/SKILL.md directory becomes a versioned, installable skill under the afonsoft publisher.
Install from ClawHub:
# Search for a skill
clawhub search "afonsoft"
# Install one skill
clawhub install @afonsoft/<skill-name>
# Or install with OpenClaw directly
openclaw skills install @afonsoft/<skill-name>
Publish all skills locally:
npm i -g clawhub
clawhub login
./publish-clawhub.sh # publish new/changed skills
./publish-clawhub.sh --dry-run # preview the publish plan
The clawhub CLI uses clawhub sync to compare local fingerprints against the registry and publishes only new or changed skills, defaulting to the next patch version.
Automatic publishing via GitHub Actions:
A workflow (.github/workflows/clawhub-publish.yml) publishes all skills when a v* tag is pushed, a release is published, or when triggered manually (workflow_dispatch). To enable it, add the repository secret:
CLAWHUB_TOKEN— your ClawHub publisher token (clawhub token createor from https://clawhub.ai/settings/tokens)
gh secret set CLAWHUB_TOKEN
📖 How to use
- Install the collection using one of the methods above. Running
./install.shadditionally generates/spec-driven:<skill>(or/spec-driven-<skill>where:is not supported) slash commands for the supported CLIs — see the table above. - Start with the orchestrator —
/spec-driven(same as/spec-driven:orchestrator) or "use the orchestrator skill" — and let it drive the spec → issues → slices → QA → PR pipeline. - Invoke an individual skill directly when you know exactly what you need (e.g.,
/spec-driven:write-specs, or "Use the create-agent-harness skill to setup this repo"). The agent loads theSKILL.mdand follows the structured workflow.
⚖️ License
MIT - See LICENSE.
🛠️ Skill Development Tools
skillxp
skillxp observes skill loading behavior across harnesses (Claude Code, Codex CLI, Antigravity). Stage a skill in a fresh fixture, invoke the harness headlessly, and see what actually reached the model with transcript evidence. Install via brew install agent-ecosystem/tap/skillxp or npm install -g skillxp. Use skillxp harnesses to list supported platforms and skillxp observe -harness <name> -install ./my-skill ... to trace skill activation and phrase loading.
📊 Skills Catalog
Browse all available skills at skills.sh.
Star History
StarMapper
StarMapper also requires a GitHub token to fetch star geolocation data. The live map image is not available until the repository is scanned.
