@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skillkit-help/knowledge/foundation/08-when-not-to-use-skills.md

@@ -0,0 +1,270 @@
+---
+title: "When NOT to Use Skills: Red Flags & Alternatives"
+purpose: "Avoiding inappropriate Skills usage, recognizing red flags"
+token_estimate: "1500"
+read_priority: "medium"
+read_when:
+  - "User considering Skills adoption"
+  - "ROI evaluation"
+  - "User describes low-frequency use case"
+  - "User has simple requirements"
+  - "User lacks technical resources"
+  - "Complement to 01-why-skills-exist"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+  read_together:
+    - "03-skills-vs-subagents-decision-tree.md"
+  read_next: []
+avoid_reading_when:
+  - "User already committed to Skills"
+  - "User has clear high-value use case"
+  - "During implementation phase"
+last_updated: "2025-11-01"
+---
+
+# When NOT to Use Skills: Red Flags & Alternatives
+
+## I. INTRODUCTION
+
+Skills are powerful but not appropriate for all situations. Understanding when NOT to use Skills prevents wasted effort, reduces scope creep, and helps identify better alternatives.
+
+**Core Principle:** Skills excel for repeatable, well-defined workflows with technical teams. If use case doesn't match this profile, consider alternatives first.
+
+**This File Helps:** Identify red flags indicating Skills are inappropriate, evaluate ROI realistically, choose better-suited alternatives.
+
+**Complement to:** `01-why-skills-exist.md` (benefits) and `03-skills-vs-subagents-decision-tree.md` (alternatives).
+
+---
+
+## II. 5 SCENARIOS WHERE SKILLS ARE INAPPROPRIATE
+
+### Scenario A: One-Time or Rare Tasks
+
+**Description:** Task needed once or very infrequently (annually, ad-hoc).
+
+**Why Inappropriate:**
+- Setup overhead (2-4 hours) not justified by single use
+- No benefit from reusability (Skills' main value)
+- Maintenance burden for unused skill
+- Token overhead without return
+
+**Example:** "Create year-end report once" - Direct prompting faster than building skill.
+
+**Red Flags:**
+- Phrases: "just this once", "one-time project", "annual task"
+- No similar future tasks planned
+- Custom requirements unlikely to repeat
+
+**Better Alternative:** Use direct prompting with clear instructions. Save conversation for reference if needed yearly.
+
+**ROI Calculation:** Setup cost 3 hours. If used 1×/year, payback never occurs. Direct prompting: 15 minutes per use, far more efficient.
+
+---
+
+### Scenario B: Non-Technical Teams Without Support
+
+**Description:** Team lacks technical skills (coding, Git, file organization) and no technical support available.
+
+**Why Inappropriate:**
+- Steep learning curve (comfort with file structures, YAML, scripting)
+- Manual distribution requires coordination skills
+- Troubleshooting needs technical expertise
+- Version control challenges without Git knowledge
+
+**Example:** Marketing team wants brand guidelines skill but has no developers. Manual upload + coordination becomes bottleneck.
+
+**Red Flags:**
+- Team has no programmers or technical members
+- Unfamiliar with Git, YAML, command line
+- Struggle with basic file organization
+- No IT support available
+
+**Better Alternative:** Use Custom Instructions for brand guidelines. Use Projects for persistent context. Both are UI-based, no technical skills required.
+
+**Support Requirement:** Minimum one technical person per 10-person team, or dedicated IT support for skill management.
+
+---
+
+### Scenario C: Rapidly Changing Requirements
+
+**Description:** Workflows, procedures, or standards change frequently (weekly/monthly).
+
+**Why Inappropriate:**
+- Constant skill updates required
+- Version synchronization overhead
+- Testing burden after each change
+- Team coordination costs multiply
+
+**Example:** Startup with evolving product development process. Procedures change weekly - skill becomes maintenance burden.
+
+**Red Flags:**
+- Phrases: "we're still figuring this out", "process in flux"
+- Organizational changes underway
+- Experimental workflows
+- No stable procedures yet
+
+**Better Alternative:** Use Projects to capture evolving context. Once stabilized (3-6 months unchanged), consider converting to Skill.
+
+**Stability Threshold:** Wait until procedures unchanged for 2-3 months before investing in skill creation.
+
+---
+
+### Scenario D: Low-Frequency Use Cases
+
+**Description:** Task occurs monthly or less frequently, low business impact.
+
+**Why Inappropriate:**
+- Token overhead (30-50 tokens always loaded) not justified
+- Maintenance effort exceeds usage value
+- Skills designed for frequent, high-value tasks
+- ROI negative at low frequency
+
+**Example:** "Format monthly newsletter" (1×/month, 10 minutes task) - skill overhead not worth automation.
+
+**Red Flags:**
+- Usage frequency: <4× per month
+- Task completion time: <30 minutes
+- Low business criticality
+- Alternatives readily available
+
+**Better Alternative:** Create reusable prompt template in Projects or shared document. Use when needed without skill overhead.
+
+**Frequency Threshold:** Skills justify investment when used 10+ times/month or task saves 1+ hours each time.
+
+---
+
+### Scenario E: Highly Sensitive Data Without Security Resources
+
+**Description:** Working with restricted data (financial, health, legal) without security expertise to audit skills.
+
+**Why Inappropriate:**
+- Third-party skills pose security risks (prompt injection, code execution, data exfiltration)
+- Comprehensive auditing requires security expertise
+- Compliance requirements (GDPR, HIPAA, SOX) demand rigorous vetting
+- Risk exposure exceeds automation benefit
+
+**Example:** Law firm wants contract analysis skill using community skill. HIPAA compliance requires security audit they can't perform.
+
+**Red Flags:**
+- Sensitive data: PII, financial, health records, legal documents
+- No security team available
+- Considering third-party/community skills
+- Compliance requirements (GDPR, HIPAA, SOX)
+
+**Better Alternative:** Use official Anthropic skills only (PowerPoint, Excel, Word, PDF) - these are vetted. Or use Projects with Custom Instructions (no code execution risk).
+
+**Security Requirement:** Comprehensive security audit mandatory for third-party skills with sensitive data. Only proceed if security expertise available.
+
+---
+
+## III. RED FLAGS CHECKLIST
+
+**Evaluate Your Use Case - If 3+ Apply, Reconsider Skills:**
+
+- [ ] Task needed <4 times per month
+- [ ] Task takes <30 minutes to complete manually
+- [ ] One-time or annual occurrence
+- [ ] Workflows still evolving or experimental
+- [ ] Team lacks technical skills (no programmers)
+- [ ] No version control knowledge (Git unfamiliar)
+- [ ] Working with highly sensitive data AND no security resources
+- [ ] Considering third-party skills for compliance-regulated data
+- [ ] No clear ROI calculation possible
+- [ ] Setup investment (3-5 hours) not justified by savings
+- [ ] Simpler alternatives exist (Projects, Custom Instructions)
+- [ ] Enterprise deployment needed but not available
+- [ ] Rapid changes expected in procedures
+
+**Scoring:** 0-2 flags: Skills likely appropriate. 3-4 flags: Consider alternatives. 5+ flags: Skills inappropriate.
+
+---
+
+## IV. DECISION MATRIX
+
+**Skills vs. Alternatives - Quick Reference:**
+
+| Situation | Use Skills | Use Projects | Use Custom Instructions | Use Direct Prompting |
+|-----------|------------|--------------|-------------------------|----------------------|
+| **Frequency** | 10+/month | Ongoing work | Every conversation | One-time/rare |
+| **Stability** | Stable (unchanged 3+ months) | Evolving | Stable preferences | Ad-hoc |
+| **Technical Skills** | Team has developers | Any skill level | Any skill level | Any skill level |
+| **Reusability** | High (across contexts) | Project-specific | Universal | No reuse |
+| **Setup Time** | 3-5 hours justified | 15-30 min | 5-10 min | None |
+| **Context Needs** | Procedural "how-to" | Accumulated context | Style/tone | Specific request |
+| **Team Size** | 3+ people sharing | Individual or small team | Individual | Individual |
+| **Data Sensitivity** | Public/Internal (audited) | Any | Any | Any |
+
+**Decision Flow:**
+1. Check frequency → If <4×/month → Not Skills
+2. Check stability → If changing weekly → Not Skills
+3. Check technical capability → If non-technical team → Not Skills
+4. Check ROI → If setup > savings → Not Skills
+5. Check alternatives → If simpler option works → Use alternative
+
+---
+
+## V. ALTERNATIVES SUMMARY
+
+**When Skills Don't Fit:**
+
+**Projects (Persistent Context):**
+- Best for: Ongoing work, evolving requirements, accumulated context
+- No technical skills required
+- Context persists across conversations
+- Example: Campaign planning, research projects
+
+**Custom Instructions (Universal Preferences):**
+- Best for: Universal preferences, tone/style, general directives
+- Applies to all conversations automatically
+- No setup complexity
+- Example: Writing style, communication preferences
+
+**Direct Prompting (Ad-Hoc Tasks):**
+- Best for: One-time tasks, rare occurrences, exploratory work
+- Zero setup time
+- Maximum flexibility
+- Example: Annual reports, one-off analysis
+
+**Subagents (Complex Workflows):**
+- Best for: Multi-step reasoning, specialized expertise, isolated context
+- Higher token cost but capability justifies
+- No filesystem dependency
+- Example: Code review, security audits
+
+**MCP (External Data Access):**
+- Best for: Real-time data, database queries, API integrations
+- Complements Skills well
+- No procedural knowledge captured
+- Example: Customer database queries
+
+**Combination Approaches:**
+- Start with Projects to capture evolving workflows
+- After stabilization (3-6 months), convert to Skills
+- Use Custom Instructions + Projects for common pattern
+- Add Skills only when reusability clear
+
+**Migration Path:** Projects → Skills (when workflows stabilize), Custom Instructions → Skills (when procedures formalize).
+
+---
+
+## WHEN TO READ NEXT
+
+**Before Skills Adoption:**
+- Understand benefits → `01-why-skills-exist.md`
+- Compare approaches → `02-skills-vs-subagents-comparison.md`
+- Use decision framework → `03-skills-vs-subagents-decision-tree.md`
+
+**For Implementation:**
+- Cost analysis → `05-token-economics.md`
+- Platform constraints → `06-platform-constraints.md`
+- Security review → `07-security-concerns.md`
+
+**If Skills Appropriate:**
+- Skip to implementation guides
+- Start small (3-5 workflows)
+- Measure ROI continuously
+
+---
+
+**FILE END - Estimated Token Count: ~1,500 tokens (~215 lines)**

package/skills/skillkit-help/template/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: your-skill-name
+description: >
+  One sentence: what this skill does and when to invoke it.
+  Use for: [list 2-3 trigger phrases users would naturally type].
+category: engineering
+# Available categories: core, engineering, documentation, planning,
+# deployment, productivity, quality, security, experimentation,
+# agent-frameworks, creative
+---
+
+## Overview
+
+[2-3 sentences: what this skill does and why it exists. Be specific.
+Bad: "Helps with code." Good: "Reviews Python functions for PEP-8
+compliance and common anti-patterns, then outputs a prioritized fix list."]
+
+---
+
+## When to Use This Skill
+
+[Optional but recommended for complex skills. List the specific
+conditions that should trigger this skill.]
+
+Examples:
+- User pastes a function and asks for a review
+- User says "check my code" or "code review"
+
+---
+
+## Section 1: [First Major Step]
+
+[Instructions for the agent. Be explicit — don't say "do the right thing,"
+say exactly what to do. Use numbered steps for ordered workflows,
+bullet points for flexible guidance.]
+
+1. Step one
+2. Step two
+3. Step three
+
+---
+
+## Section 2: [Second Major Step]
+
+[Continue as needed. Each section should have one clear responsibility.]
+
+---
+
+## Reference: [Optional — Load-on-Demand Content]
+
+[Put bulky reference material here rather than in the main flow.
+The agent loads this only when needed, saving tokens.]

package/skills/skills/adversarial-review/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: adversarial-review
+description: >
+  Adversarial review protocol for brainstorming, product planning, and technical architecture.
+  Validate ideas against reality, enforce minimum 3 bugs, severity categorization, 3 resolution paths.
+
+  USE WHEN: "adversarial review", "run adversarial protocol", "validate brainstorming",
+  "stress test idea/plan/architecture", or reviewing any planning document.
+
+  CORE PROTOCOL:
+  1. Reality vs Claims — web search min 3x diverse angle, status VALID/PARTIAL/INVALID
+  2. Acceptance Criteria — stress test specific executor capability
+  3. Mandatory Bug Quota — minimum 3 issues, force deeper dig if insufficient
+  4. Interactive Resolution — Critical/High/Medium/Low + options A(auto-fix)/B(action items)/C(deep dive)
+
+  DIFFERENTIATOR: Mandatory bug quota prevents superficial reviews. Three resolution options
+  make findings actionable. Executor stress test differentiates from generic reviews.
+metadata:
+  version: 1.0.0
+  author: V (OpenClaw)
+category: quality
+---
+
+## Section 1: Protocol Overview
+
+Adversarial Review consists of 4 mandatory stages executed sequentially.
+
+```
+Stage 1: Reality vs Claims     → web_search + web_fetch (min 3x diverse)
+Stage 2: Acceptance Criteria  → stress test executor
+Stage 3: Mandatory Bug Quota  → minimum 3 specific issues
+Stage 4: Interactive Resolution → categorization + 3 resolution options
+```
+
+**Core principle:** A good review isn't about throwing criticism, but transforming findings into decisions.
+
+---
+
+## Section 2: Stage 1 — Reality vs Claims
+
+**Objective:** Validate claims and assumptions in the document against real data and libraries.
+
+### Execution Rules
+
+1. Use web_search and web_fetch minimum **3 times** with different angles
+2. Don't just search one topic — diversify: library docs, benchmarks, user pain points, known issues
+3. Mark each claim with status: **VALID** / **PARTIAL** / **INVALID** / **UNVERIFIED**
+4. Include hidden caveats not mentioned in the original document
+
+### Search Angle Guidelines
+
+```
+Angle 1: Library/tech being used → find known limitations, version issues
+Angle 2: User pain point → find real UX research or forum complaints
+Angle 3: Benchmark/performance → find real data, not marketing claims
+Angle 4: Competitor/alternative → find if problem has been solved elsewhere
+Angle 5: Production failure → find post-mortems or known failure modes
+```
+
+### Output Format
+
+```
+**Claim:** "[claim from document]"
+**Status:** VALID / PARTIAL / INVALID / UNVERIFIED
+**Facts:** [data from search]
+**Hidden caveat:** [not mentioned in document]
+```
+
+---
+
+## Section 3: Stage 2 — Acceptance Criteria
+
+**Objective:** Not just whether the idea can be done, but whether this specific executor can do it.
+
+### Questions to Answer
+
+```
+1. Does the chosen tech stack match the executor's skills?
+2. Are there components requiring significant learning curve?
+3. Is the time estimate realistic for this executor (not team)?
+4. Are there external dependencies outside the executor's control?
+5. Is there a proof-of-concept needed before committing to production?
+```
+
+### Output Format
+
+```
+**Component:** [component/bet name]
+**Verdict:** Executable / Partial / Needs PoC first / Beyond capability
+**Reason:** [specific, honest]
+**Recommendation:** [concrete steps if there's a gap]
+```
+
+---
+
+## Section 4: Stage 3 — Mandatory Bug Quota
+
+**Objective:** Force discovery of non-obvious problems. Prevent reviews that are too soft.
+
+### Quota Rule (NON-NEGOTIABLE)
+
+```
+MINIMUM 3 specific issues must be found.
+If < 3 found → SYSTEM MUST SEARCH AGAIN in:
+  - Edge cases: what happens during extreme conditions?
+  - Performance issues: what happens at scale/high load?
+  - Architecture violations: is this design consistent?
+  - Dependency risk: what happens if library changes?
+  - UX failure mode: what happens when user does unexpected things?
+```
+
+### Severity Categories
+
+| Level | Definition | Example |
+|-------|------------|---------|
+| 🔴 Critical | Will kill the product/project if not fixed | Core promise cannot be delivered |
+| 🟠 High | Will cause significant problems in production | Performance degradation, bad UX |
+| 🟡 Medium | Real issue but has workaround | File clutter, minor inconsistency |
+| 🟢 Low | Needs attention but not urgent | Naming convention, minor inefficiency |
+
+### Bug Report Format
+
+```
+### [EMOJI] [LEVEL] #N — [Short Title]
+
+**Problem:** [specific description, not generic]
+**Trigger scenario:** [when this issue occurs]
+**Impact:** [what happens to user/product]
+**Why it's dangerous:** [why this isn't an edge case that can be ignored]
+```
+
+---
+
+## Section 5: Stage 4 — Interactive Resolution
+
+**Objective:** Every finding must have a resolution path, not just criticism.
+
+### Three Resolution Options (Always Provide All Three)
+
+```
+A. Auto-fix
+   → Directly fix the problematic idea/plan
+   → Output: new version of the fixed section
+   → Suitable for: problems with clear solutions
+
+B. Action Items
+   → Checklist to be executed by user
+   → Output: [ ] specific item with done criteria
+   → Suitable for: problems requiring user decision
+
+C. Deep Dive
+   → Detailed problem explanation with concrete examples
+   → Output: in-depth analysis + trade-offs
+   → Suitable for: problems requiring understanding before deciding
+```
+
+### Resolution Summary Table
+
+```markdown
+| # | Issue | Severity | Primary Recommendation |
+|---|-------|----------|------------------------|
+| 1 | [title] | 🔴 Critical | [one sentence fix] |
+| 2 | [title] | 🟠 High | [one sentence fix] |
+```
+
+---
+
+## Section 6: Full Protocol Template
+
+```markdown
+# Adversarial Review — [Document/Project Name]
+
+## Stage 1 — Reality vs Claims
+[Results from 3+ web searches with diverse angles]
+[Status per claim: VALID/PARTIAL/INVALID/UNVERIFIED]
+
+## Stage 2 — Acceptance Criteria
+[Stress test per component/bet]
+
+## Stage 3 — Mandatory Bug Quota (minimum 3)
+[Bug #1 — Critical/High/Medium/Low]
+[Bug #2 — ...]
+[Bug #3 — ...]
+
+## Stage 4 — Interactive Resolution
+[Per bug: option A / B / C]
+
+### Summary Priority Matrix
+| # | Issue | Severity | Primary Recommendation |
+|---|-------|----------|------------------------|
+
+## Meta-Conclusion
+[One paragraph: what changed the most? first step priority?]
+```
+
+---
+
+## Section 7: Quick Reference
+
+**Do's:**
+- Run 4 stages sequentially without skipping
+- Diversify web search angles (don't search the same topic 3x)
+- Be honest about executor capability
+- Provide all three resolution options for each Critical and High finding
+
+**Don'ts:**
+- Don't stop at < 3 issues
+- Don't create resolutions that are too generic ("just fix it")
+- Don't skip Stage 2 — executor stress test is this protocol's main differentiator
+- Don't combine multiple components in one bug report
+
+**Trigger phrases:**
+```
+"run adversarial review protocol for [document]"
+"adversarial review this"
+"validate this brainstorming hard"
+"stress test this plan"
+"find weaknesses in [plan/architecture]"
+```