Copyable AI skills

Share AI skill markdowns in a fast, collectible layout.

This theme turns every skill into a clean markdown file users can open, read, and copy directly. It is built for browsing like a modern directory and for shipping prompts like reusable assets.

Explore all skills Add a skill

278 skills available

8 skill categories

1 click to copy markdown

Featured skill

Web UI/UX Design Standards Knowledge Base

Web UI/UX Design Standards Knowledge Base This module provides a foundational guide for UI User Interface and UX User Ex...

# Web UI/UX Design Standards Knowledge Base This module provides a foundational guide for UI (User Interface) and UX (User Experience) design, ensuring consistency, readability, and accessibility across web projects. --- ## 1. Typography Typography sets the tone and ensures readability. A...

Featured skill

Web seo knowledge base

Web SEO Knowledge Base This document provides a structured overview of Search Engine Optimization SEO principles, techni...

# Web SEO Knowledge Base This document provides a structured overview of Search Engine Optimization (SEO) principles, techniques, and best practices. --- ## 1. Introduction to SEO **SEO (Search Engine Optimization)** is the practice of optimizing web content to improve visibility and...

Browse skills

Filter by title, category, or description. Every card is a markdown file with a direct copy button.

All AI & Agents AI & Agents AI knowledge base AI Prompt Backend & Infra Backend & Infra Data & Research Data & Research

AI skill markdown

Web UI/UX Design Standards Knowledge Base

401 words 72 lines

AI knowledge base

Web UI/UX Design Standards Knowledge Base This module provides a foundational guide for UI User Interface and UX User Experience design, ensuring consistency, r...

Open

# Web UI/UX Design Standards Knowledge Base

This module provides a foundational guide for UI (User Interface) and UX (User Experience) design, ensuring consistency, readability, and accessibility across web projects.

---

## 1. Typography
Typography sets the tone and ensures readability. A solid design system relies on a consistent type scale.

### Core Principles
* **Hierarchy:** Use font sizes and weights to establish a clear visual hierarchy (H1, H2, H3, Body).
* **Line Height (Leading):** Generally set between 1.4 and 1.6 for body text to maintain readability.
* **Font Units:** Use `rem` for accessibility (relative to root font size) rather than `px`.

### Standard Type Scale Example
| Element | Font Size (rem) | Weight | Use Case |
| :--- | :--- | :--- | :--- |
| **Display** | 2.5rem | 700 | Hero Sections |
| **Heading H1** | 2.0rem | 700 | Main Page Title |
| **Heading H2** | 1.5rem | 600 | Section Titles |
| **Body** | 1.0rem | 400 | Long-form content |
| **Small** | 0.875rem | 400 | Footers/Captions |

---

## 2. Spacing and The Box Model
Spacing is the "breath" of your design. Proper white space prevents cognitive overload.

&nbsp;

### The Box Model
Every element on a web page is a rectangular box. Understanding how these interact is crucial for layout control:
1. **Content:** The text or image content.
2. **Padding:** Transparent space inside the element (around the content).
3. **Border:** The edge around the padding.
4. **Margin:** Transparent space outside the element (separating it from other elements).

### Spacing Strategy (8pt Grid)
Use multiples of 8 for spacing (margin/padding) to create a harmonious layout:
* 4px, 8px, 16px, 24px, 32px, 48px, 64px.

---

## 3. Color &amp; Accessibility
Color isn't just aesthetic; it’s functional and critical for accessibility.

* **Contrast Ratios:** Follow WCAG 2.1 guidelines. Text must have a contrast ratio of at least **4.5:1** against the background.
* **Color Psychology:** Use colors consistent with brand identity and user expectations (e.g., Green for success, Red for errors).
* **Dark/Light Mode:** Ensure your color variables (`--primary-color`, `--bg-color`) support both modes automatically.

---

## 4. UI Components &amp; Interaction
Consistency is key to reducing the learning curve for users.

* **Buttons:** * Primary: Highest emphasis (CTA).
* Secondary: Supporting actions.
* Tertiary: Low-emphasis, often text-only.
* **Input Fields:** Must include clear labels and visual feedback (focus states, error states).
* **Feedback Loops:** Always provide visual confirmation (spinners, success messages) after user interaction.

---

## 5. Responsive Design Principles
Design for the smallest screen first (Mobile-First approach).

* **Breakpoints:**
* Small (Mobile): &lt; 640px
* Medium (Tablet): 640px - 1024px
* Large (Desktop): &gt; 1024px
* **Fluid Layouts:** Use CSS Grid and Flexbox for responsive containers rather than fixed widths.
* **Touch Targets:** Minimum touch target size should be 44x44 pixels for easy tapping on mobile devices.

AI skill markdown

Web seo knowledge base

592 words 87 lines

AI knowledge base

Web SEO Knowledge Base This document provides a structured overview of Search Engine Optimization SEO principles, techniques, and best practices. 1. Introductio...

Open

# Web SEO Knowledge Base

This document provides a structured overview of Search Engine Optimization (SEO) principles, techniques, and best practices.

---

## 1. Introduction to SEO
**SEO (Search Engine Optimization)** is the practice of optimizing web content to improve visibility and ranking on Search Engine Results Pages (SERPs) for organic (non-paid) traffic.

### The Three Pillars of SEO
1. **On-Page SEO:** Optimizing individual pages to rank higher and earn more relevant traffic.
2. **Off-Page SEO:** Actions taken outside of your own website to impact your rankings within search engine results pages.
3. **Technical SEO:** Improving the technical aspects of a website to increase the ranking of its pages in search engines.

---

## 2. On-Page SEO
On-page SEO focuses on the content and HTML source code of a page.

### Key Elements
* **Title Tags:** The clickable headline that appears on SERPs. Should include the primary keyword.
* **Meta Descriptions:** A summary of the page content. While not a direct ranking factor, it influences Click-Through Rate (CTR).
* **Header Tags (H1–H6):** Organize content structure. H1 is the main title; H2-H6 are subheadings.
* **Keyword Optimization:** Use keywords naturally. Avoid keyword stuffing.
* **URL Structure:** Keep URLs short, descriptive, and clean.

| Element | Best Practice |
| :--- | :--- |
| **Title Tag** | Under 60 characters, includes primary keyword. |
| **Meta Description** | Under 160 characters, compelling call to action. |
| **Content** | High quality, relevant, solves user intent. |
| **Images** | Include descriptive Alt Text and use WebP/optimized formats. |

---

## 3. Technical SEO
Technical SEO ensures search engine crawlers can efficiently access, crawl, and index your site.

### Checklist for Technical Health
* **Site Speed:** Core Web Vitals (LCP, FID/INP, CLS). Fast-loading sites rank better.
* **Mobile-Friendliness:** Ensure the site is responsive across all devices.
* **Sitemap (sitemap.xml):** Provides a roadmap of your pages to search engines.
* **Robots.txt:** Instructions for search engine crawlers on which pages to index or ignore.
* **HTTPS:** Secure sites (SSL certificates) are a ranking signal.
* **Canonical Tags:** Prevent duplicate content issues by specifying the "master" version of a page.

---

## 4. Off-Page SEO &amp; Authority
Off-Page SEO is about building the site's reputation and authority on the web.

* **Backlinks:** Links from other websites to yours. These act as "votes of confidence."
* *Focus:* Quality &gt; Quantity. A link from a high-authority site is better than 100 links from low-quality sites.
* **Content Marketing:** Create shareable content that naturally attracts links.
* **Local SEO:** For businesses with a physical location, optimize Google Business Profile to appear in local search results.

---

## 5. Keyword Research &amp; Intent
Before creating content, you must understand what your audience is searching for.

### Search Intent Categories
1. **Informational:** The user wants to learn something (e.g., "how to fix a sink").
2. **Navigational:** The user wants to go to a specific site (e.g., "Facebook login").
3. **Commercial:** The user is researching options (e.g., "best SEO tools 2026").
4. **Transactional:** The user is ready to buy (e.g., "buy running shoes online").

---

## 6. White Hat vs. Black Hat SEO

| Feature | White Hat SEO | Black Hat SEO |
| :--- | :--- | :--- |
| **Strategy** | Follows search engine guidelines. | Violates guidelines for quick gains. |
| **Longevity** | Sustainable, long-term growth. | Risky; can lead to site penalties/bans. |
| **Examples** | Quality content, proper meta tags, link building. | Keyword stuffing, cloaking, hidden text, link farms. |

---

## 7. SEO Metrics &amp; Analytics
To track progress, monitor these Key Performance Indicators (KPIs):

* **Organic Traffic:** Total visits originating from search engines.
* **Keyword Rankings:** Position of your pages for specific search terms.
* **Click-Through Rate (CTR):** Percentage of users who click your link after seeing it in search results.
* **Bounce Rate:** Percentage of visitors who navigate away after viewing only one page.
* **Conversion Rate:** Percentage of visitors who take a desired action (e.g., purchase, sign-up).

AI skill markdown

[VI] Codex Personalization

672 words 72 lines

AI Prompt

Codex Personalization & Operational Directives 1. Identity Name : Codex. Role : Senior Full stack Architect & DevOps Specialist. Primary Directive : "Security F...

Open

# Codex Personalization & Operational Directives

## 1. Identity
* **Name**: Codex.
* **Role**: Senior Full-stack Architect & DevOps Specialist.
* **Primary Directive**: "Security First", "Docker-First", and "Efficiency Above All".
* **Objective**: Act as a high-level force multiplier for the user, providing architectural guidance, code implementation, and system administration.

## 2. Communication Protocol
* **Conciseness**: Absolutely no filler phrases (e.g., "Certainly!", "I can help with that", "Based on your request").
* **Action-Oriented**: Provide direct solutions, code snippets, or commands.
* **Formatting**: Use Markdown, code blocks with explicit language tags, and tables for comparative analysis.
* **Voice**: Professional, assertive, and technically precise. Assume the user is an expert developer.

## 3. Technical Constraints (Strict Compliance)
* **Environment**: Always default to Windows PowerShell for local operations and Ubuntu 22.04 for server operations.
* **Architecture**:
    * **Laravel/PHP**: Follow PSR-12. Force Service Pattern. Validate all inputs.
    * **Security**: No hardcoded secrets. Zero trust on user input. Use parameterized queries.
    * **Optimization**: Always consider LiteSpeed/Redis/Nginx tuning before code bloat.
* **Tooling**: Prioritize Dockerized workflows for development and production stability.

## 4. Current Context Awareness (Memory Hooks)
* **Active Projects**:
    * **StatusFox**: Service monitoring platform. Maintain categorized lists of global AI/Social services.
    * **hoangtranlk.khoweb.top**: Maintain stability. Watch for CORS and server configuration.
    * **CodePen-like Platform**: Focus on security sandboxing and robust database architecture.
* **Lifestyle/Personal**:
    * Acknowledge "3 million steps" rucking challenge (4kg weight).
    * Support creative inquiries related to mythology (Yaksa, Đại Ma Vương) for content generation.

## 5. Operational Logic (The "Codex" Way)
* **Input Handling**: 
    * If a request is ambiguous, ask 1 clarifying question.
    * If a request is standard technical work, execute immediately without preamble.
* **Problem Solving**: 
    * Identify the root cause (e.g., AppArmor, Proxy, Database Indexing).
    * Provide the "Fix" followed by the "Why" (briefly).
    * If a file exists in `.agent/`, refer to it as the Source of Truth.

## 6. Prohibited Behaviors
* Do not lecture or provide unsolicited moralizing advice.
* Do not repeat existing context unless requested.
* Do not guess. If technical information is unavailable, prompt for the missing variable.

## 7. Encoding & Character Integrity (CRITICAL)
* **Default Encoding**: Tất cả output, file code, comment và tài liệu phái sinh **PHẢI** là `UTF-8` (không BOM - No BOM).
* **Vietnamese Character Handling**: 
    * Tuyệt đối không để xảy ra Mojibake. 
    * Trước khi render tiếng Việt, luôn xác định Encoding của môi trường (Editor/Database/Terminal).
    * Nếu phát hiện lỗi hiển thị ký tự (VD: `Ã©`, `á»`), Codex phải chủ động phân tích lại và re-output bằng format Unicode chuẩn.
* **Technical Compliance**:
    * Trong code PHP: Đảm bảo header `Content-Type: text/html; charset=UTF-8` được set.
    * Trong Database: Luôn ưu tiên collation `utf8mb4_unicode_ci` cho các bảng có dữ liệu tiếng Việt.

## 8. Tooling & Command Restrictions (STRICT)
* **Tooling Ban**: Cấm tuyệt đối sử dụng `rg` (ripgrep) hoặc các công cụ Linux-only.
* **Native Command Enforcement**:
    * Mặc định sử dụng **PowerShell** làm terminal ưu tiên.
    * Tìm kiếm văn bản: Sử dụng `Select-String`.
    * Cú pháp thay thế `rg "pattern"`: 
        `Get-ChildItem -Recurse | Select-String "pattern"`
    * Nếu bắt buộc dùng CMD: Sử dụng `findstr /s /i "pattern" *`.

## 9. Encoding & Mojibake Prevention
* **Default Encoding**: Mọi thao tác I/O (Input/Output) trong terminal Windows **BẮT BUỘC** phải ép về `UTF-8`.
* **PowerShell Setup**: Codex phải đề xuất thiết lập encoding cho session nếu cần thiết:
    `$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'`
* **File Processing**: Khi đọc/ghi file trên Windows, luôn kiểm tra BOM (Byte Order Mark). Ưu tiên định dạng **UTF-8 No BOM** để tương thích với mọi editor (VS Code, Notepad++).

## 10. Path Management
* Luôn sử dụng đường dẫn chuẩn Windows (`\`) hoặc `/` (PowerShell chấp nhận cả hai), không sử dụng cú pháp `~` (home directory) nếu không chắc chắn về biến môi trường `$HOME` trên máy người dùng.

AI skill markdown

/capture-content – Journalist Interview for Content Creation

874 words 208 lines

AI & Agents

name: capture content description: Journalist interview that extracts publishable content from your work through structured questions /capture content Journalis...

Open

---
name: capture-content
description: Journalist interview that extracts publishable content from your work through structured questions
---

# /capture-content - Journalist Interview for Content Creation

Claude Code skill that extracts publishable content from your work through structured interview.

## Purpose

You've just done interesting work but don't know how to talk about it yet. This skill acts as a journalist interviewing you to extract:
- What you built/discovered/solved
- Why it matters
- What to screenshot or video record
- How to frame it for your audience

## When to Use

**Session-based triggers**:
- Solved a significant problem
- Built or updated a system
- Discovered an interesting tool/workflow
- Had a meaningful realization
- Completed interesting analysis or synthesis

**Synthesis-based triggers**:
- Identified connections across multiple frameworks
- Recognized patterns from bookmark clusters
- Developed new mental model from expert synthesis

## Interview Process

The skill will ask 8-12 strategic questions designed to extract content:

### Phase 1: What Happened (3-4 questions)
- What were you working on when [interesting thing] happened?
- What specific tools/approaches did you use?
- What was the problem you were trying to solve?
- Walk me through the key moment - what exactly did you do?

### Phase 2: Why It Matters (2-3 questions)
- What surprised you about this?
- Why is this different from how it usually works?
- What does this say about [broader trend/pattern]?
- Who else struggles with this problem?

### Phase 3: Content Strategy (2-3 questions)
- Is this a "behind-the-scenes reveal" or "framework teaching" moment?
- What's the single most important insight here?
- What would make someone else care about this?
- What writing style cluster fits this best? (Technical Observer, Enthusiastic Builder, Framework Teacher)

### Phase 4: Visual Capture (1-2 questions)
- What should be screenshotted to show this?
- Would a 30-second screen recording add value?
- What's the visual "proof" that this worked?

## Output Format Options

After interview, the skill offers to generate:

1. **Twitter/X Thread** (7-12 tweets)
   - Hook using identified style cluster
   - Process breakdown with specific tools
   - Key insight delivery
   - Call to action or implication

2. **LinkedIn Post** (1,800-2,100 characters)
   - Concrete opening (what happened)
   - Process breakdown
   - Insight delivery (understated but profound)
   - Broader implication

3. **Quote-Tweet Addition** (for synthesis content)
   - Technical Observer commentary on bookmarked tool/framework
   - Your implementation experience
   - What you discovered that others miss

4. **Screenshot/Video Script**
   - What to capture visually
   - How to annotate
   - What to highlight

## Style Integration

The interview automatically applies your writing style:
- **Concrete Specificity**: Extracts exact tools, timeframes, examples
- **Observational Authority**: Frames as "here's what I witnessed"
- **Technical Accessibility**: Helps you explain without jargon
- **Confident Understatement**: Natural, authentic voice

Blends appropriate clusters based on content type:
- **Technical Observer**: Default for most content
- **Enthusiastic Builder**: When something surprisingly worked
- **Framework Teacher**: For synthesis/system content
- **Behind-the-Scenes**: For workflow reveals

## Example Interview Flow

```
Assistant: I noticed this session involved [interesting work]. Let's capture this as content.

**Phase 1: What Happened**

1. What were you trying to accomplish when you started?
User: [Answer]

2. What specific tools did you use? (Names, not "AI tools")
User: [Answer]

3. Walk me through the key moment - what exactly happened?
User: [Answer]

**Phase 2: Why It Matters**

4. What surprised you about this?
User: [Answer]

5. Why is this different from the usual way this works?
User: [Answer]

6. Who else struggles with this problem?
User: [Answer]

**Phase 3: Content Strategy**

7. What's the single most important insight from this?
User: [Answer]

8. Is this more "here's what I built" or "here's what I learned"?
User: [Answer]

9. Which style fits: Technical Observer (nuanced analysis), Enthusiastic Builder (it actually worked!), or Framework Teacher (here's the system)?
User: [Answer]

**Phase 4: Visual Capture**

10. What should I screenshot to prove this worked?
User: [Answer]

11. Would a 30-second screen recording add value? What would it show?
User: [Answer]

**Draft Generation**

Based on your answers, I'll draft:
- [Twitter thread / LinkedIn post / Quote-tweet addition]
- Screenshot/video capture instructions
- Posting guidance (timing, hashtags, mentions)
```

## Usage

```bash
# Manual invocation
/capture-content

# With context hint
/capture-content "just solved interesting problem"

# For synthesis
/capture-content synthesis

# Quick mode (fewer questions)
/capture-content quick
```

## Integration with Existing Strategy

**Resolves these strategic tensions**:
- **Evaluation vs. Publication**: Captures tool evaluations in-the-moment
- **Implementation Mode**: Extracts insights while doing the work
- **Detailed Breakdowns vs. Execution**: Reduces steps through guided interview
- **Hook Effectiveness**: Automatically applies proven patterns

**Feeds into**:
- Quote-tweet strategy (generates substantive additions)
- Framework synthesis (documents thinking for later synthesis)
- Thought leadership positioning (consistent content flow)

## Technical Implementation

The skill uses AskUserQuestion tool to conduct interview:
- Questions adapt based on previous answers
- Content type detected from responses
- Style cluster selected based on content nature
- Visual guidance tailored to platform

## Success Metrics

Track over time:
- Capture rate: % of interesting sessions that become content
- Publication rate: % of captured content that gets published
- Engagement: Which interview-generated content performs best
- Efficiency: Time from "interesting work" to "published post"

## Continuous Improvement

The system learns from:
- Which questions extract the best content
- Which style clusters drive engagement
- What visual formats work best
- When you skip questions (signals friction)

---

**Installation**: Save as `~/.claude/skills/capture-content/skill.md`

AI skill markdown

Network Security Skills

167 words 41 lines

Security

name: network description: Network penetration testing skills for service exploitation and protocol attacks. metadata: version: "1.0" category: network Network...

Open

---
name: network
description: Network penetration testing skills for service exploitation and protocol attacks.
metadata:
  version: "1.0"
  category: network
---

# Network Security Skills

Comprehensive network penetration testing skills organized by service category.

## Categories

| Category | Description | Skills |
|----------|-------------|--------|
| [Reconnaissance](reconnaissance/SKILL.md) | Network discovery | 5 |
| [Layer 2 Attacks](layer2-attacks/SKILL.md) | MITM, credential capture | 5 |
| [Auth Services](auth-services/SKILL.md) | SSH, RDP, Kerberos | 8 |
| [File Services](file-services/SKILL.md) | SMB, NFS, FTP | 7 |
| [Databases](databases/SKILL.md) | SQL, NoSQL, cache | 11 |
| [Email](email/SKILL.md) | SMTP, POP3, IMAP | 3 |
| [Infrastructure](infrastructure/SKILL.md) | DNS, SNMP, RPC | 6 |
| [Containers](containers/SKILL.md) | Docker, Kubernetes | 3 |
| [Message Queues](message-queues/SKILL.md) | MQTT, RabbitMQ, Kafka | 3 |
| [Industrial IoT](industrial-iot/SKILL.md) | ICS/SCADA protocols | 4 |
| [VPN/Tunneling](vpn-tunneling/SKILL.md) | IPSec, pivoting | 2 |
| [Security Analysis](security-analysis/SKILL.md) | SSL/TLS, evasion | 3 |
| [Wireless](wireless/SKILL.md) | WiFi attacks | 1 |
| [Other Services](other-services/SKILL.md) | Java RMI, X11, VoIP | 5 |

## Quick Reference

| Service | Port | Quick Check |
|---------|------|-------------|
| SMB | 445 | `smbclient -L` |
| SSH | 22 | `ssh -v` |
| MySQL | 3306 | `mysql -u root` |
| Redis | 6379 | `redis-cli info` |
| Docker | 2375 | `docker -H` |

AI skill markdown

JWT (referencia)

56 words 12 lines

DevOps & System

name: jwt description: "JWT y auth. Proyecto usa este skill; contenido canónico en .ai system." globs: " /auth/ ", " /core/ " JWT referencia Origen: .ai system/...

Open

---
name: jwt
description: "JWT y auth. Proyecto usa este skill; contenido canónico en .ai-system."
globs: ["**/auth/**", "**/core/**"]
---

# JWT (referencia)

**Origen:** `.ai-system/skills/jwt/SKILL.md`

Cargar el skill completo desde la ruta anterior. Resumen: access token de vida corta + refresh; validar firma, issuer y exp; no loguear tokens; HTTPS; invalidación en logout.

AI skill markdown

WordPress.com MCP

569 words 98 lines

AI & Agents

name: wordpress com mcp description: Connect Codex or other MCP capable clients to WordPress.com and run content/site/account tasks through the WordPress.com MC...

Open

---
name: wordpress-com-mcp
description: Connect Codex or other MCP-capable clients to WordPress.com and run content/site/account tasks through the WordPress.com MCP server. Use when a user asks to connect WordPress.com, authorize access, inspect sites/posts/pages/media/comments/subscribers through MCP tools, or troubleshoot WordPress.com OAuth/MCP setup.
---

# WordPress.com MCP

Create or troubleshoot a WordPress.com MCP connection by following this sequence.

## 1) Confirm connection mode

Choose one of these paths:

1. Use the hosted connector flow in Claude (recommended when the user is in Claude and wants the fastest setup).
2. Use a custom MCP client integration (use for Codex-compatible clients that can add external MCP servers).

## 2) Gather prerequisites

Collect before setup:

- A WordPress.com account with access to the target site(s).
- MCP access enabled in WordPress.com (paid plans only).
- A client that supports MCP plus OAuth 2.1 Authorization Code with PKCE.
- The official endpoints from `references/endpoints.md`.

## 3) Connect in Claude connector flow

If the user is in Claude and asks for connector setup:

1. Enable MCP access in WordPress.com settings.
2. Open Claude settings, then Connectors, then browse connectors.
3. Search for `WordPress.com` and connect.
4. Sign in to WordPress.com in the OAuth window.
5. Approve requested access.
6. Verify with:
   - `Show me my site's traffic for the last 30 days.`

Treat Claude connector access as read-only per WordPress.com announcement guidance.

## 4) Connect in a custom MCP client

Use this for Codex-compatible clients with manual MCP server configuration.

1. Register an OAuth client (dynamic registration endpoint in `references/endpoints.md`).
2. Generate PKCE `code_verifier` and `code_challenge` (`S256`).
3. Open WordPress.com authorization URL with registered `redirect_uri`.
4. Exchange authorization code for an access token.
5. Send MCP `tools/call` requests to the MCP endpoint with `Authorization: Bearer <token>`.
6. Verify with:
   - `Show my latest 5 posts for <site>.`

## 5) Validate tool access

Run at least one read operation in each relevant area:

- Site discovery: list sites, choose target site.
- Content reads: posts/pages/media/comments.
- Audience reads: followers/subscribers when relevant.

If an operation fails, capture exact error text and move to troubleshooting.

## 6) Troubleshoot quickly

- `Unauthorized` or repeated login loops:
  - Ensure OAuth 2.1 + PKCE flow is used and redirect URI exactly matches registration.
- No tools visible after connect:
  - Re-check MCP enablement, then reconnect and re-authorize.
- Missing expected sites/content:
  - Confirm account/site permissions in WordPress.com.

## 7) Prompt templates

Use or adapt:

- `List all my WordPress.com sites and summarize key stats for each.`
- `Show draft posts for <site> from the last 30 days.`
- `Summarize recent comments across <site>.`
- `Which posts on <site> have not been updated in over a year?`

## 8) Safety behavior

Default to read-oriented workflows. Before any write-like or destructive action, confirm user intent and available tool permissions.

## 9) Publish posts via REST API fallback

If MCP is connected but does not expose write tools, publish through WordPress.com REST API using the same OAuth token.

1. Confirm user intent (title/content/status and target site).
2. Use `scripts/publish_post.py`:
   - `python3 scripts/publish_post.py --site tomwillmot.com --title "My title" --content "<p>Hello</p>" --status publish`
3. Pass token via env var or argument:
   - `WPCOM_ACCESS_TOKEN='<token>' python3 scripts/publish_post.py ...`
4. Verify success from returned JSON:
   - Check `ID`, `URL`, and `status`.
5. If publish fails with permission errors:
   - Confirm the token owner has author/editor privileges on the target site.
   - Re-authorize OAuth and retry.

AI skill markdown

Quick start

820 words 205 lines

Security

name: skill authoring description: Create or update Claude Agent Skills. Use this when users want to build a new skill, scaffold a skill folder, improve an exis...

Open

---
name: skill-authoring
description: Create or update Claude Agent Skills. Use this when users want to build a new skill, scaffold a skill folder, improve an existing skill, or validate structure.
allowed-tools: "Read,Write,Edit,Bash,Glob,Grep"
---

## About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

### What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex tasks

## When to use

- "Build me a new skill for X"
- "Create a skill that does Y"
- "Validate my skill structure"
- "Improve this existing skill"
- "What sections should a skill have?"

## When NOT to use

- General coding tasks (use other skills or direct Claude)
- Questions about Claude Code itself (use claude-code-guide)
- Simple file operations that don't need a skill workflow

## Core Principles

### Concise is Key

The context window is a public good. Challenge each piece of information: "Does Claude really need this?" Prefer concise examples over verbose explanations.

### Degrees of Freedom

Match specificity to task fragility:

| Level | Use When |
|-------|----------|
| **High freedom** | Multiple valid approaches, context-dependent decisions |
| **Medium freedom** | Preferred pattern exists, some variation acceptable |
| **Low freedom** | Fragile operations, consistency critical |

Think of Claude exploring a path: a narrow bridge needs guardrails (low freedom), an open field allows many routes (high freedom).

## Anatomy of a Skill

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name + description)
│   └── Markdown instructions
├── scripts/     - Executable code (Python/Bash)
├── references/  - Documentation loaded as needed
└── assets/      - Templates, binaries for output
```

### SKILL.md Frontmatter

Only two required fields:

- `name`: The skill identifier (lowercase, hyphens)
- `description**: Triggers + purpose. Include "Use this when..." with specific conditions.

Do not add `license` or other fields.

### When to Use Each Resource Type

- **scripts/**: Deterministic operations, repeatedly rewritten code
- **references/**: Long docs, schemas, APIs, patterns Claude references
- **assets/**: Templates, icons, boilerplate copied to output

## Progressive Disclosure

Keep SKILL.md under 500 lines. Move details to references:

```
# Quick start
[essential workflow]

# Advanced
- Feature A: See [REFERENCES/A.md](REFERENCES/A.md)
- Feature B: See [REFERENCES/B.md](REFERENCES/B.md)
```

## Skill Creation Workflow

### Step 1 — Capture Requirements

See [SKILLSPEC.md](references/skill_spec.md) for the format.

### Step 2 — Plan Resources

For each example, determine:

- Does it need a script? (deterministic, repeated)
- Does it need a reference? (long docs, schemas)
- Does it need assets? (templates, boilerplate)

### Step 3 — Initialize

```bash
python "{baseDir}/scripts/init_skill.py" <skill-name> --path <output-dir>
```

### Step 4 — Fill In

1. Replace generated SKILL.md with final version
2. Add scripts to `scripts/`
3. Add docs to `references/`
4. Add assets to `assets/`
5. Delete unused sample files

### Step 5 — Gap Analysis

Verify all sections exist:

| Section | Required |
|---------|----------|
| Description | States when to use |
| When to use | 3-8 triggers |
| When NOT to use | Recommended |
| Workflow | Numbered steps |
| Tool usage | Scripts + references documented |
| Failure handling | Explicit table/list |
| Examples | Concrete walkthroughs |
| Acceptance tests | 5+ test cases |

Use [CHECKLIST.md](references/checklist.md) for full validation.

### Step 6 — Precision Analysis

Check trigger quality:

- **Overlap**: Do triggers match other common skills?
- **Specificity**: Are triggers specific enough?
- **Differentiation**: Document distinctions if overlap exists

### Step 7 — Validate

```bash
python "{baseDir}/scripts/quick_validate.py" <skill-dir>
```

## Updating Existing Skills

1. Run gap analysis against [CHECKLIST.md](references/checklist.md)
2. Run precision analysis on triggers
3. Apply fixes:
   - Improve description/triggers
   - Add missing failure handling
   - Add "When NOT to use"
   - Move long content to references/
   - Add scripts for repeated steps
4. Re-validate

## Failure Modes

| Failure | Response |
|---------|----------|
| Missing `name` or `description` | Validation fails; add required fields |
| Invalid skill name format | Use lowercase, 2-64 chars, `a-z0-9_-` |
| Placeholders (TODO) in SKILL.md | Replace with actual content before validating |
| {baseDir} reference not found | Verify path exists relative to skill folder |
| Validation errors | Fix all ERRORs before validating |

## Examples

### Creating a New Skill

User: "Build me a skill to rotate PDFs"

Assistant uses this workflow:
1. Captures requirements (rotate PDF, 3 triggers)
2. Plans resources (scripts/rotate_pdf.py)
3. Runs init_skill.py
4. Fills in SKILL.md with PDF-specific workflow
5. Adds rotate_pdf.py script
6. Validates

### Updating an Existing Skill

User: "This skill is missing failure handling"

Assistant:
1. Runs gap analysis → finds missing "Failure handling"
2. Adds failure modes table
3. Re-validates

## Acceptance Tests

| Prompt | Expected Behavior |
|--------|-------------------|
| "Build a new skill called pdf-editor" | Creates skill scaffold, runs init script |
| "Create a skill for image processing" | Follows full workflow, validates skill |
| "Validate my skill at /path/to/skill" | Runs quick_validate.py, reports issues |
| "What sections should a skill have?" | References checklist.md |
| "Help me improve my existing skill" | Runs gap analysis, suggests fixes |
| "Show me the skill spec format" | References skill_spec.md |
| "Why isn't my skill triggering?" | Checks trigger specificity, suggests improvements |

AI skill markdown

Brainstorming Ideas Into Designs

1905 words 456 lines

Development

name: brainstorming description: Use when creating or developing anything, before writing code or implementation plans refines rough ideas into fully formed des...

Open

---
name: brainstorming
description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation. Optimized for git worktree workflows and Claude CLI agent patterns.
---

# Brainstorming Ideas Into Designs

## Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.

**Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."

## Quick Reference

| Phase | Key Activities | Output |
|-------|---------------|--------|
| **1. Understanding** | Ask questions (one at a time), assess current state | Purpose, constraints, criteria |
| **2. Exploration** | Propose 2-3 approaches with trade-offs | Architecture options |
| **3. Design Presentation** | Present in 200-300 word sections | Complete design with validation |
| **4. Implementation Planning** | Choose implementation strategy | Worktree + plan OR direct implementation |

## The Process

Copy this checklist to track progress:

```
Brainstorming Progress:
- [ ] Phase 0: Current State Assessment (check working directory, git status)
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Implementation Planning (strategy chosen and executed)
```

### Phase 0: Current State Assessment

**ALWAYS start by checking the current state:**

```bash
# Check what's in the working directory
pwd
ls -la

# If it's a git repo, check status
git status
git worktree list  # See if worktrees exist
```

**Determine context:**
- Are we in a git repository?
- Are there existing worktrees?
- What files/structure already exist?
- Is this a new project or existing codebase?

**Based on findings, inform your approach:**
- New project → Start fresh with questions
- Existing project → Ask about integration points
- Multiple worktrees → Consider which worktree or if new one needed
- Clean repo → Can proceed with standard workflow

### Phase 1: Understanding

**Ask ONE question at a time** to refine the idea:

**Key questions to gather:**
- **Purpose:** What problem does this solve? Who is it for?
- **Constraints:** Time, technical, resource limitations?
- **Success criteria:** What does "done" look like?
- **Integration:** Does this connect to existing code/systems?
- **Scale:** Is this a small feature or large system?

**Example questions:**
- "What's the main problem you're trying to solve?"
- "Are there any specific technologies or patterns you want to use?"
- "Does this need to integrate with any existing systems?"
- "What's your timeline for this?"
- "How will you know when this is successful?"

**For skill development specifically:**
- "What triggers this skill? What phrases should activate it?"
- "What external data sources does it need?"
- "Should it generate files? What format?"
- "Does it need to call other skills?"

### Phase 2: Exploration

**Propose 2-3 different approaches** with clear trade-offs:

**For each approach, provide:**
- **Core architecture:** High-level structure
- **Trade-offs:** Pros and cons
- **Complexity:** Simple/Moderate/Complex
- **Best for:** What use case this serves

**Example approaches for a web service:**

**Approach 1: Serverless Functions (AWS Lambda/Netlify)**
- Architecture: Event-driven functions, managed infrastructure
- Pros: Auto-scaling, pay-per-use, minimal ops
- Cons: Cold starts, vendor lock-in, debugging challenges
- Complexity: Moderate (infrastructure-as-code)
- Best for: Variable traffic, event-driven workflows

**Approach 2: Containerized API (Docker + Express)**
- Architecture: Monolithic container, single process
- Pros: Easy to develop/debug locally, portable, standard
- Cons: Manual scaling, requires container orchestration
- Complexity: Simple to start, moderate at scale
- Best for: Steady traffic, team familiar with containers

**Approach 3: Microservices (Kubernetes)**
- Architecture: Multiple services, service mesh
- Pros: Independent scaling, team autonomy, resilient
- Cons: High operational overhead, complex debugging
- Complexity: High (networking, orchestration, monitoring)
- Best for: Large teams, complex domains, high scale

**Ask:** "Which approach resonates with your needs and constraints?"

### Phase 3: Design Presentation

**Present design in 200-300 word sections:**

**Typical sections:**
1. **Architecture Overview:** High-level diagram (in words/ASCII)
2. **Core Components:** Main modules and their responsibilities
3. **Data Flow:** How information moves through the system
4. **External Integrations:** APIs, databases, services
5. **Error Handling:** How failures are managed
6. **Testing Strategy:** Unit, integration, E2E approach
7. **Deployment:** How it gets from dev to production

**After each section:** "Does this look right so far? Any concerns or questions?"

**Stay flexible:** If the person questions something, be ready to:
- Return to Phase 1 for more clarity
- Return to Phase 2 to explore alternatives
- Adjust the current design

### Phase 4: Implementation Planning

**Once design is approved, choose implementation strategy:**

**Option A: Git Worktree Workflow (Recommended for existing repos)**

When to use:
- Working in existing git repository
- Want isolated development environment
- Making significant changes
- May need to switch back to main branch

Steps:
1. **Check current worktrees:** `git worktree list`
2. **Propose worktree location:** 
   - Adjacent to main repo: `../repo-name-feature`
   - Or subdirectory: `/tmp/worktrees/feature-name`
3. **Safety check:** Ensure directory doesn't exist
4. **Create worktree:**
   ```bash
   git worktree add -b feature/name ../feature-workspace
   cd ../feature-workspace
   ```
5. **Create planning document** in worktree
6. **Begin implementation** with context intact

**Option B: Direct Implementation (For simple features)**

When to use:
- Small, contained changes
- New project without git yet
- Quick prototype or experiment
- Working in /home/claude scratch space

Steps:
1. **Create working directory** if needed
2. **Create planning document** as markdown
3. **Begin implementation**

**Option C: Skill Development Workflow**

When to use:
- Creating or modifying a skill
- Need to bundle scripts/assets/references

Steps:
1. **Create skill directory structure:**
   ```
   /home/claude/skill-name/
   ├── SKILL.md          # Instructions for Claude
   ├── scripts/          # Python/bash scripts
   ├── assets/           # Fonts, images, templates
   └── references/       # Documentation, examples
   ```
2. **Write SKILL.md** with comprehensive instructions
3. **Add scripts** if skill needs to generate files
4. **Bundle as .zip** for user to upload

**Ask:** "Ready to move forward with [chosen option]?"

## Git Worktree Best Practices

**Based on your parallel development patterns:**

### Creating Worktrees

**Location strategy:**
```bash
# Adjacent to main repo (recommended)
git worktree add ../repo-feature feature/name

# In centralized worktree directory
git worktree add /tmp/worktrees/feature-name feature/name

# For agent-based workflows
git worktree add ../repo-architect architect/design-phase
git worktree add ../repo-bugfix bugfix/issue-123
git worktree add ../repo-docs docs/api-update
```

### Worktree Lifecycle

**Check existing worktrees:**
```bash
git worktree list
```

**Clean up when done:**
```bash
# Remove worktree
git worktree remove ../repo-feature

# Or if directory already deleted
git worktree prune
```

### Syncing Worktrees

**Keep worktrees updated:**
```bash
cd ../repo-feature
git fetch origin
git rebase origin/main  # Or merge if preferred
```

### Agent-Role Worktrees

**For specialized development roles:**
- **Architect worktree:** Design documents, architecture decisions
- **Implementation worktree:** Feature development, new code
- **Bugfix worktree:** Issue resolution, hotfixes
- **Documentation worktree:** README updates, API docs
- **Testing worktree:** Test development, QA work

Each can work independently, merge back to main when ready.

## Question Patterns

### Clarifying Questions (Use Throughout)

**Open-ended** (for understanding):
- "What problem are you trying to solve?"
- "How will users interact with this?"
- "What happens when X fails?"

**Specific** (for constraints):
- "What's your deployment target? (AWS/GCP/Local/etc.)"
- "What's your preferred language/framework?"
- "Do you have any existing code this needs to integrate with?"

**Binary** (for quick decisions):
- "Should this be synchronous or asynchronous?"
- "Do you want automated tests included?"
- "Should I create a git worktree for this?"

### Validation Questions (Phase 3)

**After each design section:**
- "Does this align with your needs?"
- "Does this look right so far?"
- "Any concerns about this approach?"
- "Anything you'd change here?"

**Before moving to implementation:**
- "Ready to move forward with this design?"
- "Would you like me to create a worktree for implementation?"
- "Should I write up a detailed implementation plan?"

## Key Principles

| Principle | Application |
|-----------|-------------|
| **Check context first** | Always assess current state before starting |
| **One question at a time** | Don't overwhelm with multiple questions |
| **YAGNI ruthlessly** | Remove unnecessary features from designs |
| **Explore alternatives** | Always propose 2-3 approaches before settling |
| **Incremental validation** | Present design in sections, validate each |
| **Flexible progression** | Go backward when needed - not rigid phases |
| **Worktree-aware** | Know when to suggest isolated workspace |
| **Skill-conscious** | Recognize when task would benefit from a skill |

## Common Scenarios

### Scenario 1: New Feature in Existing Repo

```
1. Phase 0: Check git status, current worktrees
2. Phase 1: Ask about feature purpose, integration points
3. Phase 2: Propose 2-3 implementation approaches
4. Phase 3: Present detailed design for chosen approach
5. Phase 4: Create worktree, write plan, begin implementation
```

### Scenario 2: New Project from Scratch

```
1. Phase 0: Confirm working in /home/claude or if git init needed
2. Phase 1: Deep-dive questions on requirements
3. Phase 2: Explore architectural patterns (monolith/microservices/etc)
4. Phase 3: Complete system design with all components
5. Phase 4: Create project structure, write plan
```

### Scenario 3: Creating a New Skill

```
1. Phase 0: Check /mnt/skills/user directory
2. Phase 1: Ask about trigger phrases, inputs, outputs
3. Phase 2: Explore skill architectures (simple/script-based/multi-step)
4. Phase 3: Design skill workflow, script needs, asset requirements
5. Phase 4: Create skill directory, write SKILL.md, bundle
```

### Scenario 4: Bug Fix or Refactor

```
1. Phase 0: Examine current code, understand issue
2. Phase 1: Clarify scope (just fix vs. refactor vs. redesign)
3. Phase 2: Explore fix approaches (minimal vs. comprehensive)
4. Phase 3: Present solution with test strategy
5. Phase 4: Worktree for bugfix, implement with tests
```

## Integration with Other Skills

**When brainstorming leads to skill development:**
- Use **skill-creator** skill for comprehensive skill design
- Bundle scripts, assets, references appropriately
- Write detailed SKILL.md following patterns

**When brainstorming leads to complex implementation:**
- Consider using **planning skills** for detailed task breakdown
- Create milestone-based plan in worktree
- Hand off to implementation phase with full context

**When brainstorming involves research:**
- Use **web_search** during exploration phase
- Research technologies, patterns, best practices
- Validate assumptions about libraries/frameworks

## Examples

### Example 1: API Service Design

**Phase 1 - Understanding:**
```
Q: "What will this API do?"
A: "Handle user authentication and profile management"

Q: "What's your expected scale?"
A: "Start with 1000 users, grow to 10k"

Q: "Any specific security requirements?"
A: "HIPAA compliance needed"
```

**Phase 2 - Exploration:**
```
Approach 1: OAuth2 with JWT tokens (industry standard, complex)
Approach 2: Session-based auth (simpler, server state required)
Approach 3: API keys only (simple, limited features)

[User selects Approach 1]
```

**Phase 3 - Design:**
```
Architecture: Express.js + PostgreSQL + Redis
- Auth endpoints: /login, /logout, /refresh
- Profile endpoints: /profile, /profile/update
- JWT tokens with refresh token rotation
- Redis for token blacklisting
...
```

### Example 2: Creating Research Skill

**Phase 1:**
```
Q: "What kind of research should this skill do?"
A: "Competitive analysis for product features"

Q: "What output format?"
A: "Markdown report with comparison table"
```

**Phase 2:**
```
Approach 1: Web search + structured parsing (automated)
Approach 2: Web search + manual analysis (flexible)
Approach 3: API integration (if competitors have APIs)
```

**Phase 3:**
```
Skill workflow:
1. Ask user for competitor list
2. Search for each competitor's features
3. Parse and structure findings
4. Generate comparison markdown
5. Create summary with recommendations
```

## Tips for Success

**Do:**
- ✅ Check current state before asking questions
- ✅ Ask one question at a time
- ✅ Present trade-offs clearly in alternatives
- ✅ Validate design incrementally
- ✅ Suggest worktrees for significant work
- ✅ Go backward if new info emerges
- ✅ Use web search to validate technical choices

**Don't:**
- ❌ Assume you know what user needs
- ❌ Present only one approach
- ❌ Dump entire design at once
- ❌ Force linear progression when backtracking is better
- ❌ Forget to check existing worktrees
- ❌ Skip validation questions
- ❌ Ignore git repository context

## Skill Announcement

**At the start of every brainstorming session, announce:**

"I'm using the brainstorming skill to refine your idea into a design. I'll start by checking the current project state, then ask questions to understand your needs, explore different approaches, and incrementally present a complete design for your validation."

This sets expectations and shows you're following a structured process.

---

**Remember:** This skill is about conversation, not interrogation. Stay flexible, be curious, and help your partner think through their ideas thoroughly before jumping into implementation.

AI skill markdown

mcpmu — MCP Server Manager

862 words 239 lines

AI & Agents

name: mcpmu description: Install, set up, and manage MCP servers using the mcpmu CLI. Use when the user wants to install mcpmu, register it as an MCP server in...

Open

---
name: mcpmu
description: Install, set up, and manage MCP servers using the mcpmu CLI. Use when the user wants to install mcpmu, register it as an MCP server in Claude Code, add/remove/list MCP servers, manage namespaces, set tool permissions, or expose servers via serve mode.
allowed-tools: Bash(mcpmu *), Bash(brew *), Bash(go install *), Bash(claude mcp *), Bash(which mcpmu), Bash(command -v mcpmu)
---

# mcpmu — MCP Server Manager

mcpmu is a multiplexing MCP server manager. You configure MCP servers once in mcpmu, then expose them as a single unified MCP endpoint to any agent (Claude Code, Codex, Cursor, Windsurf, etc.).

## Installing mcpmu

First check if mcpmu is already installed:
```bash
which mcpmu
```

If not installed, install via Homebrew (preferred) or Go:

**Homebrew (macOS/Linux):**
```bash
brew tap Bigsy/tap && brew install mcpmu
```

**From source (requires Go):**
```bash
go install github.com/Bigsy/mcpmu/cmd/mcpmu@latest
```

## Registering mcpmu as an MCP Server in Claude Code

After installing mcpmu, register it so Claude Code can use all mcpmu-managed servers through a single endpoint:

**Default (all servers, default namespace):**
```bash
claude mcp add mcpmu -- mcpmu serve --stdio
```

**Specific namespace:**
```bash
claude mcp add work -- mcpmu serve --stdio --namespace work
```

**With management tools (lets Claude add/remove servers via MCP):**
```bash
claude mcp add mcpmu -- mcpmu serve --stdio --expose-manager-tools
```

You can verify the registration:
```bash
claude mcp list
```

To remove mcpmu from Claude Code:
```bash
claude mcp remove mcpmu
```

### Scoped registration

Claude Code supports different scopes for MCP server registration:

```bash
claude mcp add mcpmu --scope user -- mcpmu serve --stdio       # available in all projects
claude mcp add mcpmu --scope project -- mcpmu serve --stdio    # this project only
```

## Full Setup Walkthrough

To go from zero to a working mcpmu setup in Claude Code:

1. Install mcpmu: `brew tap Bigsy/tap && brew install mcpmu`
2. Add some MCP servers: `mcpmu add context7 -- npx -y @upstash/context7-mcp`
3. Optionally create a namespace: `mcpmu namespace add work --description "Work tools"`
4. Assign servers to it: `mcpmu namespace assign work context7`
5. Register with Claude Code: `claude mcp add mcpmu -- mcpmu serve --stdio`
6. Restart Claude Code — all mcpmu-managed tools are now available

## Adding Servers

### Stdio servers (local processes)
```bash
mcpmu add <name> -- <command> [args...]
```

Examples:
```bash
mcpmu add context7 -- npx -y @upstash/context7-mcp
mcpmu add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
mcpmu add my-server --env FOO=bar --cwd /path -- ./server --flag
mcpmu add auto-server --autostart -- ./server  # start on app launch
```

### HTTP servers (remote endpoints)
```bash
mcpmu add <name> <url> [flags]
```

Examples:
```bash
mcpmu add atlassian https://mcp.atlassian.com/mcp --scopes read,write
mcpmu add figma https://mcp.figma.com/mcp --bearer-env FIGMA_TOKEN
```

### OAuth login (for HTTP servers that need it)
```bash
mcpmu mcp login <server>
mcpmu mcp login atlassian --scopes read,write
mcpmu mcp logout <server>
```

## Listing and Managing Servers

```bash
mcpmu list              # human-readable list
mcpmu list --json       # JSON output
mcpmu remove <name>     # remove (prompts for confirmation)
mcpmu remove <name> --yes  # skip confirmation
mcpmu rename <old> <new>   # rename (updates namespace/permission refs)
```

## Namespaces

Namespaces group servers into profiles — e.g. work, personal, minimal. The `namespace` subcommand can also be shortened to `ns`.

```bash
mcpmu namespace add <name> --description "desc"
mcpmu namespace list [--json]
mcpmu namespace remove <name> [--yes]
mcpmu namespace assign <namespace> <server>
mcpmu namespace unassign <namespace> <server>
mcpmu namespace default <name>
mcpmu namespace rename <old> <new>
mcpmu namespace set-deny-default <namespace> <true|false>
```

### Common namespace patterns

Create separate profiles:
```bash
mcpmu namespace add work --description "Work servers"
mcpmu namespace add personal --description "Personal projects"
mcpmu namespace assign work atlassian
mcpmu namespace assign work context7
mcpmu namespace assign personal context7
```

Create a minimal namespace that denies all tools by default, then allowlist:
```bash
mcpmu namespace add minimal --description "Lean toolset"
mcpmu namespace set-deny-default minimal true
mcpmu permission set minimal context7 resolve allow
```

## Tool Permissions

Control which tools each server exposes per namespace:

```bash
mcpmu permission list <namespace> [--json]
mcpmu permission set <namespace> <server> <tool> <allow|deny>
mcpmu permission unset <namespace> <server> <tool>
```

Examples:
```bash
mcpmu permission set work atlassian jira_search allow
mcpmu permission set work atlassian confluence_delete deny
```

## Serve Mode

Expose managed servers as a single MCP endpoint:

```bash
mcpmu serve --stdio                          # default namespace
mcpmu serve --stdio --namespace work         # specific namespace
mcpmu serve --stdio -n work --eager          # pre-start all servers
mcpmu serve --stdio --expose-manager-tools   # include mcpmu.* management tools
mcpmu serve --stdio --log-level debug        # verbose logging
```

Flags:
- `-n, --namespace` — namespace to expose
- `--eager` — pre-start all servers (default: lazy/on-demand)
- `--expose-manager-tools` — include mcpmu.* tools in tools/list
- `-l, --log-level` — debug, info, warn, error

## Connecting mcpmu to Other Agents

For Claude Code registration, see "Registering mcpmu as an MCP Server in Claude Code" above.

For other agents:

**Codex:**
```bash
codex mcp add mcpmu -- mcpmu serve --stdio
```

**Any MCP config JSON (Cursor, Windsurf, etc.):**
```json
{
  "mcpmu": {
    "command": "mcpmu",
    "args": ["serve", "--stdio"]
  }
}
```

For a namespace-specific entry:
```json
{
  "work": {
    "command": "mcpmu",
    "args": ["serve", "--stdio", "--namespace", "work"]
  }
}
```

## Interactive TUI

Run `mcpmu` with no arguments to open the terminal UI for visual server management, log monitoring, and namespace switching.

## Config

Config lives at `~/.config/mcpmu/config.json`. All commands support `--config` / `-c` to use a custom config path.

## Shell Completions

```bash
# zsh (Homebrew)
mcpmu completion zsh > "$(brew --prefix)/share/zsh/site-functions/_mcpmu"

# bash
mcpmu completion bash > /etc/bash_completion.d/mcpmu

# fish
mcpmu completion fish > ~/.config/fish/completions/mcpmu.fish
```

AI skill markdown

Ace – Agent Creates Everything

2708 words 965 lines

AI & Agents

name: ace description: "Ace Agent Creates Everything. Persistent state, parallel execution, atomic commits." Ace Agent Creates Everything You are the Ace Orches...

Open

---
name: ace
description: "Ace - Agent Creates Everything. Persistent state, parallel execution, atomic commits."
---

# Ace - Agent Creates Everything

You are the **Ace Orchestrator** - coordinate Team Leads who spawn mini-agents, maintain persistent state across sessions, and produce atomic git commits per task.

**A.C.E.** = Agent Creates Everything

---

## SPLASH SCREEN

When activated, display:

```
              ⠀⠀⠀⠀⠀⠀⠀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⡀⠀⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⢠⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⢸⡿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⢿⣧⠀⠀⠀⠀⠀
              ⢀⣀⣀⣀⣀⣸⣇⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣿⣀⣀⣀⣀⠀
              ⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇
              ⠀⠀⠀⠉⢙⣿⡿⠿⠿⠿⠿⠿⢿⣿⣿⣿⠿⠿⠿⠿⠿⢿⣿⣛⠉⠁⠀⠀
              ⠀⠀⠀⣰⡟⠉⢰⣶⣶⣶⣶⣶⣶⡶⢶⣶⣶⣶⣶⣶⣶⡆⠉⠻⣧⠀⠀⠀
              ⠀⠀⠀⢻⣧⡀⠈⣿⣿⣿⣿⣿⡿⠁⠈⢿⣿⣿⣿⣿⣿⠁⠀⣠⡿⠀⠀⠀
              ⠀⠀⠀⠀⠙⣿⡆⠈⠉⠉⠉⠉⠀⠀⠀⠀⠉⠉⠉⠉⠁⢰⣿⠋⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⣿⡇⠀⠀⠀⣠⣶⣶⣶⣶⣶⣶⣄⠀⠀⠀⢸⣿⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⠸⣷⡀⠀⠀⣿⠛⠉⠉⠉⠉⠛⣿⠀⠀⢀⣾⠇⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⠀⠘⢿⣦⡀⣿⣄⠀⣾⣷⠀⣠⣿⣀⣴⡟⠁⠀⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⠀⠀⠀⠙⠻⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀
              ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⠛⠛⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

         ╔══════════════════════════════════════════════════╗
         ║                    A C E                         ║
         ║          Agent Creates Everything                ║
         ╚══════════════════════════════════════════════════╝

    ┌──────────────────────────────────────────────────────────┐
    │  3 Team Leads      →  Unlimited Mini-Agents              │
    │  Persistent State  →  Zero Context Loss                  │
    │  Atomic Commits    →  Perfect Traceability               │
    └──────────────────────────────────────────────────────────┘

    BUILD ANYTHING:
      Apps    →  dashboards, landing pages, portals
      APIs    →  REST, GraphQL, microservices
      Tools   →  CLI, scripts, automations
      Agents  →  AI workflows, LLM pipelines

    COMMANDS:
      /ace:new-project     Start new project
      /ace:map-codebase    Analyze existing code
      /ace:progress        Check status
      /ace:help            All commands

    What's the plan?
```

### Terminal Scripts (Optional - Manual Only)

**Note:** These scripts are standalone terminal tools for visual flair. They do NOT integrate with Claude Code - they're for users who want extra terminal aesthetics.

```bash
# Run manually in a separate PowerShell window:
.\.ace\scripts\ace.bat splash      # Show splash art
.\.ace\scripts\ace.bat dashboard   # Show project status
.\.ace\scripts\ace.bat progress    # Live status monitoring
```

Available scripts:
- `splash.ps1` - Displays the Ace art
- `dashboard.ps1` - Shows project status from STATE.md
- `execution.ps1` - Displays Team Lead progress animation

**Important:** These are cosmetic tools only. All actual Ace functionality works through Claude Code conversation - no terminal scripts required.

---

## ARCHITECTURE

```
+=====================================================================+
|                    ACE UNIFIED ARCHITECTURE                          |
+=====================================================================+

                    PERSISTENCE LAYER
    +----------------------------------------------------------+
    | PROJECT.md | ROADMAP.md | STATE.md | ISSUES.md | codebase/ |
    +----------------------------------------------------------+
                              |
                              v
                   CONTEXT MANAGEMENT
    +----------------------------------------------------------+
    | Budget: 200k/agent | Checkpoints | Session Handoff        |
    +----------------------------------------------------------+
                              |
                              v
                   ORCHESTRATION LAYER
    +----------------------------------------------------------+
    |                    ORCHESTRATOR (you)                     |
    |                          |                                |
    |        +----------------+----------------+                 |
    |        |                |                |                 |
    |        v                v                v                 |
    |    +-------+        +-------+        +-------+            |
    |    | ALPHA |        | BETA  |        | GAMMA |            |
    |    | Lead  |        | Lead  |        | Lead  |            |
    |    +---+---+        +---+---+        +---+---+            |
    |        |                |                |                 |
    |     +--+--+          +--+--+          +--+--+             |
    |     |a1|a2|          |b1|b2|          |g1|g2|             |
    |     +--+--+          +--+--+          +--+--+             |
    |      mini             mini             mini               |
    |     agents           agents           agents              |
    +----------------------------------------------------------+
                              |
                              v
                    GIT INTEGRATION
    +----------------------------------------------------------+
    | Per-task commits | Zone-aware staging | {type}({phase}):  |
    +----------------------------------------------------------+
```

---

## SLASH COMMANDS (26 Total)

### Project Lifecycle (4)

| Command | Description |
|---------|-------------|
| `/ace:new-project` | Initialize project with PROJECT.md |
| `/ace:create-roadmap` | Build ROADMAP.md and STATE.md |
| `/ace:map-codebase` | Analyze existing code (7 documents) |
| `/ace:init` | Quick-start project initialization |

### Phase Management (7)

| Command | Description |
|---------|-------------|
| `/ace:plan-phase [N]` | Create PLAN.md for phase N |
| `/ace:execute-plan` | Run current plan |
| `/ace:add-phase` | Append phase to roadmap |
| `/ace:insert-phase [N]` | Insert urgent phase at position N |
| `/ace:remove-phase [N]` | Remove phase N |
| `/ace:discuss-phase [N]` | Pre-planning context discussion |
| `/ace:research-phase [N]` | Deep ecosystem research |

### Validation (3)

| Command | Description |
|---------|-------------|
| `/ace:validate-plan` | Validate current plan structure |
| `/ace:validate-zones` | Check zone assignments and conflicts |
| `/ace:recover-execution` | Recover from failed execution |

### Progress & Display (4)

| Command | Description |
|---------|-------------|
| `/ace:progress` | Show status and next steps |
| `/ace:status` | Quick status check |
| `/ace:list-phases` | List all phases in roadmap |
| `/ace:show-plan` | Display current plan details |

### Verification (3)

| Command | Description |
|---------|-------------|
| `/ace:verify-work` | User acceptance testing |
| `/ace:plan-fix` | Plan fixes for UAT issues |
| `/ace:consider-issues` | Review deferred issues |

### Session Management (3)

| Command | Description |
|---------|-------------|
| `/ace:pause-work` | Create handoff document |
| `/ace:resume-work` | Restore from last session |
| `/ace:resume-task [id]` | Resume specific task |

### Configuration (2)

| Command | Description |
|---------|-------------|
| `/ace:config` | View/edit configuration |
| `/ace:help` | Show all commands |

### Natural Language Support

**Users don't need to memorize commands.** Ace understands natural language and routes to the appropriate action.

#### Activation Phrases (Start Ace)
| User Says | Action |
|-----------|--------|
| "Ace" / "ace" | Show splash, auto-detect project state |
| "Start Ace" | Same as above |
| "Hey Ace" | Same as above |

#### Project Creation
| User Says | Routes To |
|-----------|-----------|
| "Create a new project" | `/ace:new-project` |
| "Start a new project called [name]" | `/ace:new-project "[name]"` |
| "I want to build [description]" | `/ace:new-project` + gather details |
| "Help me build a [type] app" | `/ace:new-project` with type hint |
| "Initialize the project" | `/ace:init` |
| "Set up [name] project" | `/ace:new-project "[name]"` |

#### Roadmap & Planning
| User Says | Routes To |
|-----------|-----------|
| "Create a roadmap" / "Plan the phases" | `/ace:create-roadmap` |
| "What phases do we need?" | `/ace:create-roadmap` |
| "Break this into phases" | `/ace:create-roadmap` |
| "Plan phase [N]" / "Plan the [first/next] phase" | `/ace:plan-phase [N]` |
| "What should we do first?" | `/ace:plan-phase 1` |
| "Create tasks for phase [N]" | `/ace:plan-phase [N]` |
| "Let's discuss phase [N]" | `/ace:discuss-phase [N]` |
| "Research phase [N]" | `/ace:research-phase [N]` |

#### Execution
| User Says | Routes To |
|-----------|-----------|
| "Execute" / "Run the plan" / "Start building" | `/ace:execute-plan` |
| "Do it" / "Go" / "Build it" | `/ace:execute-plan` |
| "Start working" / "Begin execution" | `/ace:execute-plan` |
| "Let's implement this" | `/ace:execute-plan` |

#### Progress & Status
| User Says | Routes To |
|-----------|-----------|
| "Status" / "Progress" / "Where are we?" | `/ace:progress` |
| "What's done?" / "Show progress" | `/ace:progress` |
| "How far along are we?" | `/ace:progress` |
| "Show the plan" / "What's the current plan?" | `/ace:show-plan` |
| "List phases" / "Show all phases" | `/ace:list-phases` |

#### Session Management
| User Says | Routes To |
|-----------|-----------|
| "Resume" / "Continue" / "Pick up where we left off" | `/ace:resume-work` |
| "Resume task [id]" | `/ace:resume-task [id]` |
| "Pause" / "Stop for now" / "Save progress" | `/ace:pause-work` |
| "I need to take a break" | `/ace:pause-work` |

#### Verification & Fixes
| User Says | Routes To |
|-----------|-----------|
| "Check the work" / "Review what was built" | `/ace:verify-work` |
| "Test it" / "Does it work?" | `/ace:verify-work` |
| "Fix the issues" / "Address the problems" | `/ace:plan-fix` |
| "Look at deferred issues" | `/ace:consider-issues` |

#### Codebase Analysis
| User Says | Routes To |
|-----------|-----------|
| "Analyze this codebase" / "Map the code" | `/ace:map-codebase` |
| "Understand this project" | `/ace:map-codebase` |
| "What does this codebase do?" | `/ace:map-codebase` |

#### Help & Config
| User Says | Routes To |
|-----------|-----------|
| "Help" / "What can you do?" | `/ace:help` |
| "Show commands" / "What commands exist?" | `/ace:help` |
| "Settings" / "Configuration" | `/ace:config` |

#### Smart Routing Logic

When user input doesn't match exact patterns, apply this logic:

```
1. Check if STATE.md exists:
   - NO: User likely needs /ace:new-project
   - YES: Continue to step 2

2. Check current state in STATE.md:
   - Status "Ready to plan": Suggest /ace:plan-phase
   - Status "Plan ready": Suggest /ace:execute-plan
   - Status "Executed": Suggest /ace:verify-work
   - Status "Paused": Suggest /ace:resume-work

3. If user mentions building/creating something specific:
   - No project exists: /ace:new-project with their description
   - Project exists: /ace:plan-phase with their feature as context

4. If unclear, use AskUserQuestion:
   "What would you like to do?"
   - Start a new project
   - Continue current project
   - Check progress
   - Something else
```

#### Example Conversations

**Non-technical user:**
```
User: "I want to build a dashboard for my team"
Ace: [Shows splash] Let's create your dashboard!
         → Routes to /ace:new-project "Team Dashboard"
         → Gathers requirements via conversation
         → Creates PROJECT.md automatically
```

**Returning user:**
```
User: "ace"
Ace: [Shows splash] Welcome back!
         → Reads STATE.md
         → Shows: "You're on Phase 2, Plan 1 - ready to execute"
         → Asks: "Continue with execution?"
```

**Progress check:**
```
User: "how's it going?"
Ace: → Routes to /ace:progress
         → Shows visual progress board
```

---

## SUPPORTED PROJECT TYPES

```
+-------------+----------------------+---------------------------+
|    TYPE     |     DESCRIPTION      |         USE CASE          |
+-------------+----------------------+---------------------------+
| frontend    | React, Next, Vue     | UI, dashboards, pages     |
| backend     | Node, Express        | APIs, services            |
| fullstack   | Full applications    | End-to-end apps           |
| automation  | Scripts, CLI         | DevOps, tooling           |
| agentic     | AI agents, LLM       | Autonomous systems        |
| library     | npm packages         | Reusable code             |
| monorepo    | Multi-package        | Large-scale projects      |
| custom      | User-defined         | Any structure             |
+-------------+----------------------+---------------------------+
```

---

## WORKFLOW PHASES

### Overview

```
+-------+    +---------+    +---------+    +-----------+
| INIT  | -> | ANALYZE | -> | PLAN    | -> | EXECUTE   | -> [REPEAT]
+-------+    +---------+    +---------+    +-----------+

INIT:     /ace:new-project + /ace:create-roadmap
ANALYZE:  Auto-detect project type, read STATE.md
PLAN:     /ace:plan-phase creates PLAN.md with max 3 tasks
EXECUTE:  /ace:execute-plan spawns Team Leads in parallel
```

---

## PHASE 1: INITIALIZE (First Time Only)

### For Greenfield Projects

```
/ace:new-project
        |
        v
   PROJECT.md created
        |
        v
/ace:create-roadmap
        |
        v
   ROADMAP.md + STATE.md created
```

### For Brownfield Projects

```
/ace:map-codebase
        |
        v
   .ace/planning/codebase/ created (7 docs)
        |
        v
/ace:new-project (informed by codebase map)
        |
        v
   Continue as above...
```

---

## PHASE 2: ANALYZE

### 2.1 Load Persistent State

**CRITICAL:** Always read STATE.md first to restore context.

```
START OF ANY SESSION:
        |
        v
   Read .ace/planning/STATE.md
        |
        v
   Read .ace/planning/PROJECT.md
        |
        v
   Know exactly where we left off
```

### 2.2 Detect Project Type

```
DETECTION FLOW (priority order):

     Scan Codebase
           |
           v
    +------+------+
    |  packages/  | ---> monorepo
    +------+------+
           |
    +------+------+
    | src/agents/ | ---> agentic
    +------+------+
           |
    +------+------+
    | app/api/**  | ---> fullstack
    +------+------+
           |
    +------+------+
    | src/routes/ | ---> backend
    +------+------+
           |
    +------+------+
    | components/ | ---> frontend
    +------+------+
           |
    +------+------+
    | scripts/**  | ---> automation
    +------+------+
           |
    +------+------+
    | src/index   | ---> library
    +------+------+
           |
           v
      Ask User (custom)
```

If uncertain, use **AskUserQuestion** tool.

---

## PHASE 3: PLAN

### 3.1 Create PLAN.md

**CRITICAL:** Maximum 3 tasks per plan to prevent context degradation.

Each task should be:
- Atomic (single responsibility)
- Testable (verifiable outcome)
- Zone-aligned (assigned to one Team Lead)

### 3.2 Visual Plan Display

```
+==============================================================+
|                    ACE PLAN v4.0                             |
+==============================================================+
|  Request: [User's request]                                   |
|  Type: [project type]         Stack: [detected stack]        |
|  Phase: [X] of [Y]            Plan: [A] of [B]               |
+==============================================================+

REQUEST: "[feature description]"
              |
              v
+-------------+-------------+-------------+
|                                         |
v                 v                       v
+--------+     +--------+            +--------+
| ALPHA  |     |  BETA  |            | GAMMA  |
| [role] |     | [role] |            | [role] |
+--------+     +--------+            +--------+
| zone:  |     | zone:  |            | zone:  |
| [files]|     | [files]|            | [files]|
+--------+     +--------+            +--------+
| task:  |     | task:  |            | task:  |
| - xxx  |     | - xxx  |            | - xxx  |
+--------+     +--------+            +--------+
    |              |                      |
    v              v                      v
mini-agents   mini-agents           mini-agents

+==============================================================+
|  Mode: PARALLEL          Max Tasks: 3                        |
+==============================================================+
```

### 3.3 Zone Assignment Table

```
+----------+------------------+------------------+------------------+
|   TYPE   |      ALPHA       |       BETA       |      GAMMA       |
+----------+------------------+------------------+------------------+
| frontend | layout, styles   | components,hooks | pages            |
| backend  | models, schemas  | services, utils  | routes, ctrl     |
| fullstack| api, server, db  | components, lib  | pages, layouts   |
| automate | scripts, core    | utils, config    | cli, entry       |
| agentic  | agents, memory   | tools, prompts   | orchestrator     |
| library  | core, lib        | types, utils     | index, exports   |
| monorepo | packages/shared  | packages/ui      | apps/**          |
+----------+------------------+------------------+------------------+
```

### 3.4 Get Approval

Use **AskUserQuestion** tool:
- Question: "Ready to execute this plan?"
- Options: "Yes, execute" / "Adjust plan"

---

## PHASE 4: EXECUTE

### 4.1 Execution Strategies

**Strategy A: Fully Autonomous** (no checkpoints in plan)
- Spawn subagent for entire plan
- Subagent creates SUMMARY.md and commits
- Main context: orchestration only (~5% usage)

**Strategy B: Segmented** (has verify checkpoints)
- Execute in segments between checkpoints
- Subagent for autonomous segments
- Main context for checkpoints
- Aggregate results -> SUMMARY -> commit

**Strategy C: Decision-Dependent** (has decision checkpoints)
- Execute in main context
- Decision outcomes affect subsequent tasks
- Quality maintained through small scope (max 3 tasks)

### 4.2 Spawn Team Leads in PARALLEL

**CRITICAL:** Send ALL 3 Task tool calls in ONE message.

```
SPAWNING:

     ORCHESTRATOR
          |
          | (single message, 3 Task calls)
          |
    +-----+-----+-----+
    |           |     |
    v           v     v
  ALPHA      BETA   GAMMA
   [*]        [*]    [*]
 spawned   spawned spawned
```

### 4.3 Team Lead Prompt Template

```
You are Ace Team Lead [ALPHA/BETA/GAMMA].

+------------------------------------------+
|  PROJECT: [path]                         |
|  TYPE: [project type]                    |
|  PHASE: [X]-[Y] (plan name)              |
+------------------------------------------+

YOUR ZONE (files you OWN):
+------------------------------------------+
| [file patterns]                          |
+------------------------------------------+

FORBIDDEN (other teams own):
+------------------------------------------+
| [forbidden patterns]                     |
+------------------------------------------+

YOUR TASK:
+----+-------------------------------------+
| 1  | [task description]                  |
+----+-------------------------------------+

EXECUTION RULES:
- Analyze complexity: 3+ files -> spawn mini-agents
- Stay within YOUR ZONE
- After task completion: stage YOUR files only
- Commit format: {type}({phase}-{plan}): {task-name}

TO SPAWN MINI-AGENTS:
Send multiple Task calls in ONE message:
- description="alpha-1: [subtask]"
- description="alpha-2: [subtask]"

WHEN DONE:
1. Stage files: git add [your-files-only]
2. Commit: git commit -m "{type}({phase}-{plan}): {task-name}"
3. Report: files created/modified + commit hash
```

### 4.4 Progress Board

During execution, show:

```
+==============================================================+
|                    EXECUTION PROGRESS                        |
+==============================================================+

+------------------+------------------+------------------+
|      ALPHA       |       BETA       |      GAMMA       |
+------------------+------------------+------------------+
| Status: WORKING  | Status: WORKING  | Status: DONE     |
+------------------+------------------+------------------+
| [*] task 1       | [*] task 1       | [*] task 1       |
| Commit: abc123   | Commit: def456   | Commit: ghi789   |
+------------------+------------------+------------------+
| Mini-agents: 2   | Mini-agents: 1   | Mini-agents: 0   |
| a-1: working     | b-1: done        |                  |
| a-2: working     |                  |                  |
+------------------+------------------+------------------+

Progress: [================>   ] 75%
```

### 4.5 Deviation Handling

During execution, handle discoveries automatically:

1. **Auto-fix bugs** - Fix immediately, document in Summary
2. **Auto-add critical** - Security/correctness gaps, add and document
3. **Auto-fix blockers** - Can't proceed without fix, do it and document
4. **Ask about architectural** - Major structural changes, stop and ask user
5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue

Only rule 4 requires user intervention.

---

## PHASE 5: INTEGRATE

### 5.1 Collect Results

```
+==============================================================+
|                    RESULTS COLLECTED                         |
+==============================================================+

ALPHA reported:
+------------------------------------------+
| Created: models/user.ts                  |
| Created: models/post.ts                  |
| Commit: abc1234                          |
+------------------------------------------+

BETA reported:
+------------------------------------------+
| Created: services/userService.ts         |
| Commit: def5678                          |
+------------------------------------------+

GAMMA reported:
+------------------------------------------+
| Created: routes/user.ts                  |
| Commit: ghi9012                          |
+------------------------------------------+
```

### 5.2 Run Quality Checks

```
QUALITY CHECKS:
+--------------+--------+
| TypeScript   |   ?    |
| Lint         |   ?    |
| Build        |   ?    |
| Tests        |   ?    |
+--------------+--------+
```

Run: `npm run typecheck && npm run build`

### 5.3 Create SUMMARY.md

Generate SUMMARY.md with:
- Tasks completed
- Commit hashes for each task
- Deviations documented
- Issues discovered

### 5.4 Update STATE.md

Update:
- Current position (phase, plan, status)
- Performance metrics (duration, velocity)
- Session continuity info
- Decisions/blockers if any

### 5.5 Metadata Commit

After all tasks committed, one final metadata commit:

```bash
git add .ace/planning/phases/XX-name/{phase}-{plan}-PLAN.md
git add .ace/planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
git add .ace/planning/STATE.md
git add .ace/planning/ROADMAP.md
git commit -m "docs({phase}-{plan}): complete [plan-name] plan"
```

### 5.6 Completion Report

```
+==============================================================+
|               ACE COMPLETE                                   |
+==============================================================+

Phase: [X] of [Y] | Plan: [A] of [B]

+------------------+------------------+------------------+
|      ALPHA       |       BETA       |      GAMMA       |
+------------------+------------------+------------------+
| [*] COMPLETE     | [*] COMPLETE     | [*] COMPLETE     |
| 2 files          | 1 file           | 2 files          |
| Commit: abc123   | Commit: def456   | Commit: ghi789   |
+------------------+------------------+------------------+

TOTALS:
+------------------------------------------+
| Files created:    5                      |
| Commits:          4 (3 tasks + 1 docs)   |
| Quality checks:   PASSED                 |
+------------------------------------------+

NEXT: /ace:plan-phase [N+1] or /ace:verify-work
+==============================================================+
```

---

## GIT INTEGRATION

### Commit Strategy

| Event | Commit? | Format |
|-------|---------|--------|
| Project init | YES | `docs: initialize [name] ([N] phases)` |
| PLAN.md created | NO | Commit with plan completion |
| **Task completed** | YES | `{type}({phase}-{plan}): {task-name}` |
| **Plan completed** | YES | `docs({phase}-{plan}): complete [plan-name]` |
| Handoff created | YES | `wip: [phase-name] paused at task [X]/[Y]` |

### Commit Types

- `feat` - New feature/functionality
- `fix` - Bug fix
- `test` - Tests only
- `refactor` - Code cleanup
- `perf` - Performance improvement
- `chore` - Dependencies, config
- `docs` - Documentation/planning

### Per-Task Commit Rules

1. Stage only files modified by that task
2. Commit immediately after task completes
3. Record commit hash for SUMMARY.md
4. **NEVER use:** `git add .` or `git add -A`

### Zone-to-CommitType Mapping

```
+----------+--------+---------------------------------------------+
|   ZONE   |  TYPE  |  TYPICAL COMMIT TYPE                        |
+----------+--------+---------------------------------------------+
| ALPHA    | models | feat (new models), fix (schema fixes)       |
| BETA     | services| feat (new logic), refactor (cleanup)       |
| GAMMA    | routes | feat (endpoints), fix (routing bugs)        |
+----------+--------+---------------------------------------------+
```

---

## STATE PERSISTENCE

### STATE.md Structure

```markdown
# Project State

## Project Reference
See: .ace/planning/PROJECT.md
**Core value:** [One-liner]
**Current focus:** [Current phase name]

## Current Position
Phase: [X] of [Y] ([Phase name])
Plan: [A] of [B] in current phase
Status: [Ready to plan / In progress / Complete]
Last activity: [YYYY-MM-DD] -- [What happened]

Progress: [=========>          ] 45%

## Performance Metrics
- Total plans completed: [N]
- Average duration: [X] min

## Accumulated Context
### Decisions
- [Phase X]: [Decision summary]

### Deferred Issues
[From ISSUES.md]

### Blockers
None yet.

## Session Continuity
Last session: [YYYY-MM-DD HH:MM]
Resume file: [Path or "None"]
```

### STATE.md Lifecycle

| When | Action |
|------|--------|
| Project init | Create STATE.md with position "Phase 1 ready to plan" |
| Every session start | Read STATE.md first |
| After plan execution | Update position, metrics, decisions |
| After phase complete | Update progress bar, clear resolved blockers |
| On pause | Set resume file path |

---

## BROWNFIELD CODEBASE MAPPING

### /ace:map-codebase

Spawns **4 parallel Explore agents** to analyze codebase:

| Agent | Analyzes | Produces |
|-------|----------|----------|
| Agent 1 | Technology | STACK.md + INTEGRATIONS.md |
| Agent 2 | Organization | ARCHITECTURE.md + STRUCTURE.md |
| Agent 3 | Quality | CONVENTIONS.md + TESTING.md |
| Agent 4 | Issues | CONCERNS.md |

Output: `.ace/planning/codebase/` with 7 documents

Use before `/ace:new-project` for existing codebases.

---

## ROBUSTNESS FEATURES

### Retry Logic

```
Agent Failed
     |
     v
+----+----+
| Retry 1 | ---> Success? ---> Continue
+----+----+
     |
     v (if failed)
+----+----+
| Retry 2 | ---> Success? ---> Continue
+----+----+
     |
     v (if failed)
Report failure to user
```

### Validation Gates

```
VALIDATION:
+---------+     +---------+     +---------+
| Task    | --> | Check   | --> | Valid?  |
| done?   |     | files   |     |         |
+---------+     +---------+     +---------+
                                    |
                              +-----+-----+
                              |           |
                              v           v
                            [YES]       [NO]
                              |           |
                              v           v
                          Commit      Fix Agent
```

### Context Budget

- Maximum 3 tasks per PLAN.md
- Each mini-agent gets fresh 200k context
- Prevents quality degradation from accumulated context

---

## BEST PRACTICES

```
+----+--------------------------------------------------+
| 1  | Read STATE.md first - restore session context    |
| 2  | Detect project type - scan codebase              |
| 3  | Max 3 tasks per plan - prevent context bloat     |
| 4  | Parallel everything - Team Leads + mini-agents   |
| 5  | Zone ownership - no file conflicts               |
| 6  | Atomic commits - one per task                    |
| 7  | Progress boards - visual task tracking           |
| 8  | Update STATE.md - after every significant action |
| 9  | Quality checks - run build/lint/test             |
+----+--------------------------------------------------+
```

---

## CUSTOM ZONES

```
"Build with:
- ALPHA: src/a/**
- BETA: src/b/**
- GAMMA: src/c/**"

     +--------+     +--------+     +--------+
     | ALPHA  |     |  BETA  |     | GAMMA  |
     | src/a  |     | src/b  |     | src/c  |
     +--------+     +--------+     +--------+
```

---

## COMMAND ROUTING

When user types a command, route to the appropriate `.ace/commands/*.md` file:

```
User Input                    Route To
----------                    --------
/ace:new-project    ->   commands/new-project.md
/ace:execute-plan   ->   commands/execute-plan.md
/ace:progress       ->   commands/progress.md
...
```

Each command file contains:
- Objective
- Context to load
- Process steps
- Success criteria

AI skill markdown

YAMS Blackboard Skill (OpenCode)

784 words 140 lines

AI & Agents

name: yams blackboard description: Blackboard plugin for OpenCode built on YAMS, enabling agents to share findings, tasks, and context via a persistent knowledg...

Open

---
name: yams-blackboard
description: Blackboard plugin for OpenCode built on YAMS, enabling agents to share findings, tasks, and context via a persistent knowledge graph.
license: GPL-3.0
compatibility: claude-code, opencode
metadata:
  tools: |
    bb_register_agent, bb_list_agents,
    bb_post_finding, bb_get_finding, bb_query_findings, bb_search_findings, bb_acknowledge_finding, bb_resolve_finding,
    bb_create_task, bb_get_ready_tasks, bb_claim_task, bb_update_task, bb_complete_task, bb_fail_task, bb_query_tasks,
    bb_create_context, bb_get_context_summary, bb_set_context, bb_recent_activity, bb_stats, bb_connections
  categories: agent, coordination, blackboard, knowledge-graph
---

# YAMS Blackboard Skill (OpenCode)

## Overview

This skill implements the classic **blackboard pattern** for multi‑agent systems using **YAMS** as the shared memory layer. Agents can:

- Register themselves and publish capabilities.
- Post **findings** (tagged markdown documents) that other agents can query or search.
- Create, claim, and complete **tasks** that coordinate work across agents.
- Group related work into **contexts** and explore relationships via YAMS’ graph commands.

All data is stored in YAMS, so the same powerful search (`yams grep`, `yams search`) and graph (`yams graph`) capabilities are available.

## Quick Reference

```bash
# Start a YAMS session (optional, auto‑starts on OpenCode session creation)
yams session start --name "opencode-session"

# Register an agent
bb_register_agent '{"id":"scanner","name":"Security Scanner","capabilities":["security","code-review"]}'

# Post a finding
bb_post_finding '{"agent_id":"scanner","topic":"security","title":"SQL Injection","severity":"high","confidence":0.94,"content":"..."}'

# Search findings
bb_search_findings '{"query":"SQL injection"}'

# Create and claim a task
bb_create_task '{"title":"Fix injection","type":"fix","created_by":"coordinator","priority":1}'
bb_claim_task '{"task_id":"t-abc123","agent_id":"fixer"}'
```

## Tools

| Tool | Description |
|------|-------------|
| `bb_register_agent` | Register an agent with ID, name, and capabilities |
| `bb_list_agents` | List all registered agents |
| `bb_post_finding` | Store a finding (markdown front‑matter) on the blackboard |
| `bb_get_finding` | Retrieve a finding by its ID |
| `bb_query_findings` | Query findings by topic, agent, severity, etc. |
| `bb_search_findings` | Semantic search across finding contents |
| `bb_acknowledge_finding` | Mark a finding as acknowledged by an agent |
| `bb_resolve_finding` | Mark a finding as resolved with resolution details |
| `bb_create_task` | Create a new coordination task |
| `bb_get_ready_tasks` | List pending tasks with no unmet dependencies |
| `bb_claim_task` | Claim a pending task for an agent |
| `bb_update_task` | Update task status, findings, or artifacts |
| `bb_complete_task` | Mark task as completed and optionally attach results |
| `bb_fail_task` | Mark task as failed with an error message |
| `bb_query_tasks` | Query tasks by type, status, assignee, etc. |
| `bb_create_context` | Create a named context to group work |
| `bb_get_context_summary` | Generate a markdown summary of a context |
| `bb_set_context` | Set the active context for subsequent operations |
| `bb_recent_activity` | Retrieve recent findings and tasks |
| `bb_stats` | Return blackboard statistics (agents, findings, tasks) |
| `bb_connections` | Explore graph connections for an entity path |

## Compaction / Context Recovery

- This skill auto-injects a blackboard summary into `output.context` during OpenCode compaction hooks (`experimental.session.compacting` and `session.compacted`).
- For broader YAMS memory after compaction, use `yams list` (replaces the removed `yams hook`): `yams list --owner opencode --since 24h --limit 20 --format markdown` with optional `--pbi`, `--task`, `--phase`, `--metadata key=value` (repeatable), and `--match-any-metadata`.

Example:

```bash
yams list --owner opencode --since 24h --limit 20 --format markdown --metadata phase=checkpoint
```

### Owner / multi-agent convention

- When registering agents or writing findings/tasks via this plugin, use the shared owner `opencode` so multiple agents can read the same YAMS records. Retrieval: `yams list --owner opencode ...`.

### Canonical agent registration

```bash
bb_register_agent '{"id":"opencode-coordinator","name":"OpenCode Coordinator","capabilities":["coordination","routing","summary"]}'
```

## Example Workflow

```typescript
// Agent A registers and posts a security finding
bb_register_agent({ id: "scanner", name: "Scanner", capabilities: ["security"] })
bb_post_finding({
  agent_id: "scanner",
  topic: "security",
  title: "SQL Injection in auth.ts",
  severity: "high",
  confidence: 0.96,
  content: "Unsanitized user input reaches SQL query...",
})

// Agent B discovers the finding and creates a remediation task
bb_search_findings({ query: "SQL injection" })
bb_create_task({
  title: "Fix SQL injection",
  type: "fix",
  created_by: "coordinator",
  priority: 0,
})

// Agent B claims and works on the task
bb_claim_task({ task_id: "t-123", agent_id: "fixer" })
bb_update_task({ task_id: "t-123", status: "working" })
bb_complete_task({ task_id: "t-123", findings: ["f-xyz"] })

// Resolve the original finding
bb_resolve_finding({ finding_id: "f-abc", agent_id: "fixer", resolution: "Parameterized queries added" })
```

## Development

The TypeScript implementation lives in `blackboard.ts`.  Building the plugin:

```bash
bun install
bun run build
```

Run tests with `bun test`.

---
For more details see the plugin’s `README.md` and the YAMS skill definition at `docs/skills/yams/SKILL.md`.

1 2 3 … 24 Next

How it works

Write a skill as markdown, assign a category, publish it, and let users copy the file directly from the card or the detail page.

Open directory