@mclawnet/agent 0.5.9 → 0.6.2

package/skills/project-learnings/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: project-learnings
+description: Capture, organize, and apply project-specific learnings and institutional knowledge. Use when documenting debugging insights, architectural decisions, workflow quirks, environment-specific gotchas, or any reusable knowledge gained during development.
+disable-model-invocation: true
+---
+
+# Project Learnings
+
+Systematically capture, organize, and retrieve project-specific knowledge so that insights gained during development are never lost and always available when needed.
+
+## Overview
+
+Every project accumulates implicit knowledge — environment quirks, debugging tricks, why certain decisions were made, what approaches were tried and failed. This knowledge typically lives in individual developers' heads and is lost when they leave or context-switch. This skill provides a structured way to capture, categorize, and retrieve project learnings.
+
+## When to Use
+
+- After debugging a non-obvious issue (capture the root cause and fix)
+- After making an architectural decision (capture the why, not just the what)
+- When discovering an environment-specific quirk (CI behavior, platform differences)
+- After a failed approach (capture what was tried and why it didn't work)
+- During onboarding (contribute new-comer observations about confusing areas)
+- During retrospectives (extract actionable learnings)
+
+## When NOT to Use
+
+- **API documentation** — use the `technical-writing` skill
+- **Code comments** — inline comments belong in the code
+- **Meeting notes** — use the `meeting-insights-analyzer` skill
+- **Architecture planning** — use the `architecture` skill
+
+## Learning Categories
+
+### 1. Debugging Insights
+
+Knowledge gained from investigating bugs.
+
+**Template:**
+```markdown
+### [Short title describing the issue]
+
+**Category**: debugging
+**Date**: YYYY-MM-DD
+**Confidence**: high | medium | low
+
+**Symptom**: What was observed (error message, unexpected behavior)
+**Root Cause**: Why it happened
+**Fix**: What resolved it
+**Prevention**: How to prevent recurrence
+**Time to Diagnose**: How long did it take? (helps calibrate future estimates)
+```
+
+**Example:**
+```markdown
+### WebSocket reconnection fails after laptop sleep
+
+**Category**: debugging
+**Date**: 2024-03-15
+**Confidence**: high
+
+**Symptom**: After resuming from sleep, WebSocket shows "connected" but
+messages are silently dropped. No error in console.
+**Root Cause**: The server closes idle connections after 30s, but the
+client's heartbeat check uses the old connection object without verifying
+it's actually connected at the TCP level.
+**Fix**: Added TCP-level health check in `ws-client.ts:reconnect()` that
+sends a ping and waits for pong before marking as connected.
+**Prevention**: Added integration test that simulates connection drop.
+**Time to Diagnose**: 3 hours (misleading "connected" status was the blocker)
+```
+
+### 2. Architectural Decisions
+
+Why we chose approach A over approach B.
+
+**Template:**
+```markdown
+### [Decision title]
+
+**Category**: architecture
+**Date**: YYYY-MM-DD
+**Status**: active | superseded by [link]
+
+**Context**: What situation prompted this decision
+**Decision**: What we chose
+**Alternatives Considered**: What we didn't choose and why
+**Consequences**: What this decision makes easier/harder
+**Review Trigger**: When to reconsider (e.g., "if user count exceeds 10K")
+```
+
+### 3. Environment & Tooling Quirks
+
+Platform-specific behavior, CI gotchas, toolchain issues.
+
+**Template:**
+```markdown
+### [Quirk title]
+
+**Category**: environment
+**Date**: YYYY-MM-DD
+**Affects**: [CI | local dev | staging | production | specific OS]
+
+**Behavior**: What happens
+**Workaround**: How to deal with it
+**Permanent Fix**: (if known)
+```
+
+**Example:**
+```markdown
+### npm ci fails on CI with ENOMEM on 2GB runners
+
+**Category**: environment
+**Date**: 2024-02-20
+**Affects**: CI (GitHub Actions ubuntu-latest)
+
+**Behavior**: `npm ci` OOMs during the install step on the default
+2GB runner when node_modules exceeds 1.5GB.
+**Workaround**: Use `--max-old-space-size=1536` or switch to a 4GB runner.
+**Permanent Fix**: Audit and remove unused dependencies to reduce install size.
+```
+
+### 4. Failed Approaches
+
+Approaches that were tried and abandoned (and why).
+
+**Template:**
+```markdown
+### [What was attempted]
+
+**Category**: failed-approach
+**Date**: YYYY-MM-DD
+
+**Goal**: What we were trying to achieve
+**Approach**: What we tried
+**Why It Failed**: Specific reason (not just "didn't work")
+**What Worked Instead**: The approach we used
+**Lesson**: What to remember for next time
+```
+
+### 5. Performance Observations
+
+Benchmarks, scaling behavior, resource usage patterns.
+
+**Template:**
+```markdown
+### [Observation title]
+
+**Category**: performance
+**Date**: YYYY-MM-DD
+**Measured On**: [hardware/environment details]
+
+**Observation**: What was measured
+**Numbers**: Specific metrics
+**Implication**: What this means for the project
+**Action**: What to do about it (if anything)
+```
+
+### 6. Process & Workflow
+
+Team conventions, release processes, review practices.
+
+**Template:**
+```markdown
+### [Process title]
+
+**Category**: process
+**Date**: YYYY-MM-DD
+
+**What**: Description of the process or convention
+**Why**: Reason it exists
+**When to Use**: Trigger conditions
+**Exceptions**: When to deviate from this process
+```
+
+## Capture Process
+
+### When to Capture
+
+Capture a learning **immediately** when:
+- You spend >30 minutes debugging something
+- You discover the solution to a non-obvious problem
+- You make a decision that future-you will need context for
+- You hit a platform/tool quirk that wasted time
+- You try an approach and it fails for non-obvious reasons
+
+### How to Capture
+
+**Quick capture** (during work — don't interrupt flow):
+```markdown
+## Quick Learning: [title]
+[2-3 sentences: what happened, what we learned, what to do differently]
+```
+
+**Full capture** (when you have time — use the templates above):
+Fill in the full template for the appropriate category.
+
+### Where to Store
+
+Store learnings in a discoverable location:
+
+**Option A: Project docs folder**
+```
+docs/
+  learnings/
+    debugging.md      # All debugging insights
+    architecture.md   # All architectural decisions
+    environment.md    # All environment quirks
+    README.md         # Index and categories
+```
+
+**Option B: Single file** (for smaller projects)
+```
+docs/LEARNINGS.md     # All learnings in one file, organized by category
+```
+
+**Option C: ADR-style numbered files** (for architectural decisions)
+```
+docs/decisions/
+  001-use-postgres.md
+  002-event-sourcing.md
+  003-api-versioning.md
+```
+
+## Retrieval Patterns
+
+### Finding Relevant Learnings
+
+When facing a problem, check learnings first:
+
+1. **Search by symptom**: "Have we seen this error before?"
+2. **Search by component**: "What do we know about the auth module?"
+3. **Search by category**: "What environment quirks should I know about?"
+4. **Search by date**: "What did we learn during the last refactoring?"
+
+### Applying Learnings
+
+Before starting work on a component:
+1. Read relevant learnings for that area
+2. Check for failed approaches (avoid repeating them)
+3. Review architectural decisions (understand constraints)
+4. Note any environment quirks that might affect the work
+
+## Maintenance
+
+### Regular Review
+
+**Monthly**: Scan learnings for entries that are:
+- **Outdated**: The issue was permanently fixed → mark as resolved
+- **Superseded**: A newer decision replaced an older one → link them
+- **Low confidence**: Marked as "medium" or "low" → verify or remove
+
+### Quality Standards
+
+Good learnings are:
+- **Specific**: Exact error messages, file paths, line numbers
+- **Actionable**: Clear what to do with the knowledge
+- **Dated**: So readers know if it's still relevant
+- **Categorized**: Easy to find when needed
+
+Bad learnings are:
+- "React can be tricky sometimes" (too vague)
+- "Fixed the bug" (no root cause or prevention)
+- "We should probably use TypeScript" (opinion without context)
+
+## Anti-Patterns
+
+### Knowledge Hoarding
+**Problem**: Learnings live in one person's head, not in docs.
+**Fix**: Make "capture a learning" part of the PR checklist for non-trivial changes.
+
+### Write-Only Documentation
+**Problem**: Learnings are captured but never consulted.
+**Fix**: Add "check learnings" as a step when starting work on a module. Reference them in PRs.
+
+### Stale Knowledge
+**Problem**: Learnings from 2 years ago that no longer apply.
+**Fix**: Monthly review cycle. Date and confidence-tag every entry.
+
+### Over-Documentation
+**Problem**: Every trivial fix gets a full learning entry.
+**Fix**: Only capture non-obvious insights. The 30-minute rule: if it took >30 min to figure out, it's worth documenting.

package/skills/security-audit/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: security-audit
+description: Perform systematic security audits on codebases using OWASP Top 10 methodology, dependency analysis, and secret detection. Use when reviewing code for vulnerabilities, assessing application security posture, checking for leaked credentials, or evaluating authentication and authorization implementations.
+---
+
+# Security Audit
+
+A systematic security audit skill that evaluates codebases against the OWASP Top 10, checks for leaked secrets and vulnerable dependencies, and reviews authentication, authorization, and input validation. Every finding includes severity, confidence, and remediation guidance.
+
+## Overview
+
+This skill guides a thorough, methodical security audit. The auditor acts as a security engineer whose job is to identify vulnerabilities before they reach production.
+
+Core principles:
+- **Be systematic.** Follow the audit process in order. Do not skip categories even when the codebase looks simple.
+- **Be evidence-based.** Every finding must reference specific code locations. Do not report theoretical vulnerabilities without evidence.
+- **Be proportional.** Authentication endpoints deserve more scrutiny than internal utility functions.
+- **Be actionable.** Every vulnerability identified must include a concrete remediation path.
+- **Be honest about severity.** Do not inflate findings. A low-risk issue is not a critical vulnerability.
+
+## When to Use
+
+- Auditing a codebase for security vulnerabilities before release
+- Reviewing code changes that touch authentication, authorization, or data handling
+- Checking for hardcoded secrets, API keys, or credentials in source code
+- Evaluating dependency security and known vulnerability exposure
+- Assessing OWASP Top 10 compliance for a web application
+- Performing a security review after a reported incident or breach
+
+## When NOT to Use
+
+- **General code review** -- use the `code-review` skill instead; it includes a security dimension
+- **Writing tests** -- use the `testing` skill for test implementation
+- **Infrastructure/network security** -- this skill covers application code, not server hardening
+- **Compliance auditing** (SOC2, HIPAA, PCI-DSS) -- those require domain-specific frameworks
+
+## Security Audit Process
+
+Follow these five phases in order. Complete each phase before moving to the next.
+
+### Phase 1: Attack Surface Mapping
+
+Before examining code for vulnerabilities, understand what is exposed.
+
+- Identify all entry points: HTTP endpoints, WebSocket handlers, CLI inputs, message queue consumers
+- Map data flows: trace user-controlled input from entry to storage, display, or external system
+- Identify trust boundaries: where does unauthenticated become authenticated? User-level become admin?
+- Catalog sensitive data: PII, credentials, tokens, financial data
+- Note third-party integrations: OAuth providers, payment gateways, external APIs
+
+### Phase 2: OWASP Top 10 Review
+
+Evaluate the codebase against each category. Check the specific items listed.
+
+**A01: Broken Access Control** -- Authorization enforced on every endpoint (not just UI)? User A cannot access user B's resources? Admin functions protected at API layer? CORS restrictive? No privilege escalation via role/permission manipulation?
+
+**A02: Cryptographic Failures** -- Sensitive data encrypted at rest and in transit? Passwords hashed with bcrypt/scrypt/argon2? No hardcoded encryption keys? No deprecated algorithms (DES, RC4, MD5)? CSPRNG used for tokens and nonces?
+
+**A03: Injection** -- SQL queries parameterized? NoSQL queries safe? OS commands avoided or escaped? Template expressions safe from injection? User input sanitized before HTML insertion? GraphQL depth-limited?
+
+**A04: Insecure Design** -- Rate limits on auth and API endpoints? Business logic validated server-side? No account enumeration or unlimited resource creation?
+
+**A05: Security Misconfiguration** -- Default credentials disabled? Stack traces hidden in production? HTTP security headers set (CSP, HSTS, X-Frame-Options)? Debug endpoints excluded from production?
+
+**A06: Vulnerable Components** -- Dependencies pinned to specific versions? Known CVEs in direct or transitive dependencies? Unused dependencies removed?
+
+**A07: Authentication Failures** -- Session tokens regenerated after login? Session timeouts configured? Passwords validated for complexity? Failed logins rate-limited? JWTs validated correctly (algorithm, expiration, issuer)?
+
+**A08: Data Integrity Failures** -- No deserialization of untrusted data? No `eval()` or `Function()` with user input? Dependencies verified with integrity checks?
+
+**A09: Logging Failures** -- Auth events logged? Authorization failures logged? Logs protected from injection? Sensitive data excluded from logs?
+
+**A10: SSRF** -- User-supplied URLs fetched? Allowlists enforced? Internal network addresses blocked (127.0.0.1, 10.x, 169.254.169.254)?
+
+### Phase 3: Secret and Credential Detection
+
+Scan the codebase for exposed secrets:
+
+- API keys, tokens, or passwords in source files or configuration
+- Private keys (RSA, EC, PGP) committed to the repository
+- Database connection strings with embedded credentials
+- Cloud provider credentials (AWS access keys, Azure connection strings, GCP service account keys)
+- Variables named `password`, `secret`, `token`, `api_key`, `credential` near string literals
+- High-entropy strings (40+ alphanumeric characters) in source code
+- `.env` files with real values instead of placeholders
+- PEM-format private keys (`-----BEGIN.*PRIVATE KEY-----`)
+- Secrets removed from code but still present in git history
+
+### Phase 4: Input Validation Review
+
+Examine every point where external data enters the application.
+
+- Is every input validated for type, length, range, and format server-side?
+- Are file uploads validated for type, size, and content (not just extension)?
+- Are URL parameters, headers, and cookies validated alongside request body?
+- Is output encoding context-aware (HTML, JavaScript, URL, CSS, SQL)?
+- Are rich text inputs sanitized with allowlist (not denylist)?
+- Is path traversal prevented (`../` sequences stripped or rejected)?
+- Do validation errors reveal minimal information (no stack traces or SQL)?
+- Is error handling consistent across all endpoints?
+
+### Phase 5: Authentication and Authorization Deep Review
+
+**Authentication:**
+- Constant-time password comparison (preventing timing attacks)?
+- Password reset tokens single-use, time-limited, and high-entropy?
+- Session storage server-side or in signed/encrypted cookies?
+- OAuth/OIDC flows correct (state parameter, PKCE for public clients)?
+- Refresh token rotation and revocation on compromise?
+
+**Authorization:**
+- Enforced at data access layer, not just middleware?
+- Object-level permissions checked (can user X access resource Y)?
+- Function-level permissions checked (can user X perform action Z)?
+- Centralized authorization mechanism (not scattered across handlers)?
+- Permission checks consistent across all CRUD operations per resource?
+
+## Severity Classification
+
+- **Critical**: Actively exploitable -- data breach, auth bypass, RCE, or privilege escalation. Remediate immediately.
+- **High**: Exploitable under realistic conditions with significant impact. Remediate before release.
+- **Medium**: Requires specific conditions to exploit or has limited impact. Remediate in current cycle.
+- **Low**: Minor weakness or defense-in-depth improvement. Remediate when convenient.
+- **Informational**: Best practice recommendation with no direct exploitability.
+
+### Assignment Rules
+
+- Remotely exploitable without authentication: Critical at minimum.
+- Requires authenticated access: High at minimum, unless impact is negligible.
+- Requires physical access or insider knowledge: Medium at most.
+- Defense-in-depth with no direct exploit path: Low or Informational.
+- When in doubt between two levels, choose the higher one.
+
+### Confidence Levels
+
+- **Confirmed**: Verified through code analysis with a clear exploit path.
+- **High**: Very likely real but depends on runtime behavior not fully visible in code.
+- **Medium**: Plausible but context incomplete. State what information is needed.
+- **Low**: Potential concern that may be mitigated by factors not visible in review.
+
+## Finding Format
+
+```
+### [SEVERITY] [Short title]
+
+**Category:** OWASP A01-A10 | Secret Exposure | Input Validation | Auth/AuthZ | Dependency
+**Location:** `path/to/file.ts:42-58`
+**Confidence:** Confirmed | High | Medium | Low
+**CWE:** CWE-[number] [name] (if applicable)
+
+**Vulnerability:** [What is wrong, why it is exploitable, and what the impact would be.]
+
+**Evidence:** [Code snippet or pattern demonstrating the vulnerability.]
+
+**Remediation:** [Concrete fix with code example or specific library/function to use.]
+```
+
+## Security Audit Report Template
+
+```
+# Security Audit Report
+
+**Project:** [Name and version]
+**Scope:** [Full codebase, specific modules, or PR diff]
+**Date:** [YYYY-MM-DD]
+
+## Executive Summary
+
+**Overall risk level:** Critical | High | Medium | Low
+**Findings:** Critical: [N] | High: [N] | Medium: [N] | Low: [N] | Info: [N]
+
+[Two to three sentences summarizing security posture and most significant findings.]
+
+## Attack Surface Summary
+
+- **Entry points:** [N] | **Sensitive data types:** [List]
+- **Third-party integrations:** [List] | **Trust boundaries:** [List]
+
+## OWASP Top 10 Compliance
+
+| Category | Status | Findings |
+|----------|--------|----------|
+| A01: Broken Access Control | Pass / Fail / N/A | [N] |
+| A02: Cryptographic Failures | Pass / Fail / N/A | [N] |
+| A03: Injection | Pass / Fail / N/A | [N] |
+| A04: Insecure Design | Pass / Fail / N/A | [N] |
+| A05: Security Misconfiguration | Pass / Fail / N/A | [N] |
+| A06: Vulnerable Components | Pass / Fail / N/A | [N] |
+| A07: Auth Failures | Pass / Fail / N/A | [N] |
+| A08: Data Integrity Failures | Pass / Fail / N/A | [N] |
+| A09: Logging Failures | Pass / Fail / N/A | [N] |
+| A10: SSRF | Pass / Fail / N/A | [N] |
+
+## Detailed Findings
+
+[All findings ordered by severity: Critical first, then High, Medium, Low, Informational.]
+
+## Remediation Priority
+
+| # | Finding | Effort | Impact |
+|---|---------|--------|--------|
+| 1 | [Title] | Low/Med/High | [Description] |
+
+## Positive Observations
+
+[Security practices done well. Omit if nothing stands out.]
+
+## Recommendations
+
+[Strategic recommendations: process improvements, tooling, training.]
+```

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: skill-creator
+description: Create new ClawNet skills by guiding the user through requirements gathering, SKILL.md authoring, validation, and installation. Use when the user wants to create a custom skill or package domain knowledge as a reusable capability.
+---
+
+# Skill Creator
+
+A meta-skill for creating new ClawNet skills. Guides the process from requirements gathering through SKILL.md authoring, validation, and installation.
+
+## Overview
+
+ClawNet skills are Markdown files (`SKILL.md`) that teach an AI agent how to perform a specific task. This skill helps you create high-quality skills that trigger correctly, provide actionable guidance, and produce consistent output.
+
+Skills are stored at `~/.clawnet/.claude/skills/{name}/SKILL.md` and are automatically discovered by all ClawNet agents through lazy loading — only the name and description are loaded at startup (~2% of context), with full content injected on demand when the skill is triggered.
+
+## When to Use
+
+- Creating a new custom skill for a specific domain or workflow
+- Packaging recurring prompt patterns into a reusable skill
+- Extending ClawNet's capabilities with specialized knowledge
+- Formalizing a team's best practices into a skill that agents follow
+
+## When NOT to Use
+
+- **Creating MCP servers** — use the `mcp-builder` skill instead; MCP servers provide tools, skills provide guidance
+- **One-off prompt engineering** — if you need something once, just ask directly
+- **System configuration** — skills are not for changing agent settings or permissions
+
+## Skill Creation Process
+
+### Step 1: Requirements Gathering
+
+Before writing anything, clarify:
+
+1. **What capability does this skill provide?** Describe in one sentence what the agent should be able to do after loading this skill.
+2. **What triggers this skill?** What would a user say or ask that should activate it? List 3-5 example triggers.
+3. **What should NOT trigger this skill?** List scenarios where a similar request should use a different skill or no skill.
+4. **What is the expected output?** Describe the format, structure, and content of what the skill produces.
+5. **What knowledge does the skill encode?** List the domain expertise, processes, or best practices that make this skill valuable.
+
+### Step 2: Name and Description
+
+**Name rules:**
+- Lowercase kebab-case: `my-skill-name`
+- Maximum 64 characters
+- Descriptive but concise: prefer `security-audit` over `comprehensive-security-vulnerability-analysis-tool`
+- No generic names: avoid `helper`, `utils`, `tool`
+
+**Description rules:**
+- Maximum 1024 characters (one sentence ideal, two sentences maximum)
+- Start with an action verb: "Perform...", "Generate...", "Analyze...", "Design..."
+- Include the trigger context: "Use when..." or "Activate when..."
+- Be specific enough to avoid false triggers from unrelated requests
+- Be broad enough to capture all valid use cases
+
+**Description quality test:**
+- Would this description trigger on the example inputs from Step 1? (Must be yes)
+- Would this description trigger on the "should NOT trigger" examples? (Must be no)
+- Could someone unfamiliar with the skill understand when to use it from the description alone? (Must be yes)
+
+### Step 3: Structure Design
+
+Choose sections based on what your skill does. Not every section is needed for every skill.
+
+**Required sections:**
+- YAML frontmatter (`name` + `description`)
+- Overview (what and why, 5-15 lines)
+- When to Use (trigger conditions)
+- When NOT to Use (avoid false triggers)
+- Core content (the actual guidance — process, checklist, framework, etc.)
+
+**Optional sections (include if relevant):**
+- Output Format / Template (if the skill produces structured output)
+- Examples (if the process is complex and benefits from worked examples)
+- Common Patterns / Variations (if the skill adapts to different scenarios)
+- Anti-Patterns / Pitfalls (if there are common mistakes to avoid)
+- Related Skills (if this skill works in combination with others)
+
+### Step 4: Write SKILL.md
+
+Follow the template below. Key writing principles:
+
+- **Be specific, not abstract.** "Check for SQL injection in all user input fields" is better than "Consider security implications."
+- **Be actionable.** Every section should tell the agent what to DO, not just what to KNOW.
+- **Use checklists for verification.** Agents follow checklists reliably.
+- **Include examples for complex patterns.** Show, don't just tell.
+- **Keep it focused.** One skill, one capability. If you need two capabilities, create two skills.
+
+### Step 5: Validate
+
+Run through this validation checklist before installing:
+
+- [ ] YAML frontmatter is valid (`name` ≤64 chars, `description` ≤1024 chars)
+- [ ] Name is lowercase kebab-case with no spaces
+- [ ] Description starts with an action verb
+- [ ] Description includes "Use when..." trigger context
+- [ ] "When to Use" section lists 3+ concrete trigger scenarios
+- [ ] "When NOT to Use" section lists at least one exclusion
+- [ ] Core content provides step-by-step actionable guidance
+- [ ] No external hard dependencies (tools/libraries are optional, not required)
+- [ ] Output format is defined if the skill produces structured output
+- [ ] Total length is appropriate: 100-600 lines (under 100 is likely too thin; over 600 risks context bloat)
+
+### Step 6: Install
+
+Save the skill to the ClawNet skills directory:
+
+```
+~/.clawnet/.claude/skills/{name}/SKILL.md
+```
+
+The skill will be automatically discovered by all ClawNet agents on their next startup. No restart is needed for agents that are already running — they will pick it up when the skill directory is rescanned.
+
+## SKILL.md Template
+
+```markdown
+---
+name: {kebab-case-name}
+description: {Action verb} {what it does}. Use when {trigger context}.
+---
+
+# {Skill Title}
+
+{One paragraph overview: what this skill does, why it exists, and what makes it valuable.}
+
+## When to Use
+
+- {Trigger scenario 1}
+- {Trigger scenario 2}
+- {Trigger scenario 3}
+
+## When NOT to Use
+
+- {Exclusion 1 — and which skill to use instead}
+- {Exclusion 2}
+
+## {Core Process / Framework / Methodology}
+
+### Step 1: {First step}
+
+{Detailed guidance for this step. Be specific and actionable.}
+
+### Step 2: {Second step}
+
+{Detailed guidance.}
+
+### Step 3: {Third step}
+
+{Detailed guidance.}
+
+## Output Format
+
+{Describe or show the expected output structure.}
+
+## {Additional Sections as Needed}
+
+{Common patterns, anti-patterns, examples, related skills, etc.}
+```
+
+## Description Writing Guide
+
+The description is the most important part of a skill — it determines when the skill is triggered. A poorly written description leads to missed triggers or false activations.
+
+**Pattern: Action + Target + Trigger**
+
+```
+{Action verb} {what} {on what}. Use when {specific trigger context}.
+```
+
+**Good examples:**
+- "Perform systematic security audits on codebases. Use when reviewing code for vulnerabilities, checking OWASP compliance, or assessing dependency security."
+- "Generate structured changelogs from git history. Use when preparing a release, documenting changes, or creating version notes."
+- "Analyze meeting transcripts to extract action items, decisions, and key insights. Use when processing meeting notes or recordings."
+
+**Bad examples (and why):**
+- "Help with security stuff." — Too vague, will trigger on anything security-related.
+- "A comprehensive tool for analyzing, reviewing, auditing, and improving security posture across all dimensions of a codebase including dependencies, configurations, and runtime behavior." — Too long, tries to cover everything, description > 1024 chars risk.
+- "Security audit." — No trigger context, no action verb, agent cannot tell when to use it.
+
+## Common Skill Types
+
+### Analysis Skill
+Input → structured analysis → report. Examples: code-review, security-audit, performance-analysis.
+
+Key sections: Analysis Framework (step-by-step), Dimensions/Criteria (what to evaluate), Finding Format (how to report issues), Summary Template.
+
+### Generation Skill
+Requirements → artifact. Examples: changelog-generator, skill-creator, technical-writing.
+
+Key sections: Input Requirements, Generation Process, Output Format/Template, Quality Checklist.
+
+### Process Skill
+Step-by-step workflow. Examples: testing (TDD cycle), pair-programming, deep-research.
+
+Key sections: Process Steps (detailed, ordered), Decision Points (when to branch), Common Patterns, Anti-Patterns.
+
+### Review Skill
+Input → findings → recommendations. Examples: code-review, architecture (review checklist).
+
+Key sections: Review Criteria, Severity/Confidence Calibration, Finding Format, Summary Template.