opcrew 0.1.6 → 0.1.8

package/dist/skills/find-skills/SKILL.md

@@ -0,0 +1,531 @@
+---
+name: find-skills
+description: Dual-mode skill discovery system. Reactive mode helps users discover and install agent skills when they ask questions like "how do I do X". Proactive mode enables Captain to analyze projects and tasks to automatically identify and install needed skills. This skill supports both user-driven queries and Captain's autonomous skill selection.
+---
+
+# Find Skills
+
+This skill provides a dual-mode system for discovering and installing skills from the open agent skills ecosystem.
+
+## Dual-Mode Architecture
+
+### Reactive Mode
+Respond to user queries when they explicitly ask for skill recommendations or express interest in extending capabilities. The user initiates the process.
+
+### Proactive Mode
+Captain autonomously analyzes projects and tasks to identify skill gaps and install needed capabilities without explicit user requests. This is crew-driven and automatic.
+
+---
+
+## When to Use This Skill
+
+### Reactive Mode Triggers
+Use reactive mode when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+### Proactive Mode Triggers
+Captain should use proactive mode when:
+
+- **Project initialization**: Starting work on a new project or major feature
+- **Task complexity detected**: A task requires specialized knowledge not in current skill set
+- **Repeated failures**: Multiple attempts at a task indicate a capability gap
+- **Technology mismatch**: Project uses tech stack that differs from crew's default capabilities
+- **Quality requirements**: Task demands best practices or domain-specific patterns
+
+---
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+---
+
+## Reactive Mode: Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+---
+
+## Captain's Proactive Workflow
+
+When operating in proactive mode, Captain follows this 6-step process:
+
+### Step 1: Analyze Context
+- Review project structure, dependencies, and configuration files
+- Identify primary technologies: frameworks, languages, build tools
+- Note existing patterns: testing frameworks, CI/CD setup, documentation style
+
+### Step 2: Identify Capability Gaps
+- Compare project requirements against current crew skill set
+- Ask: "Does the crew have domain knowledge for this tech stack?"
+- Flag areas where specialized knowledge would improve quality or speed
+
+### Step 3: Search for Relevant Skills
+- Use targeted queries based on identified gaps
+- Prioritize skills matching the project's exact tech stack
+- Consider cross-cutting concerns (security, performance, accessibility)
+
+### Step 4: Evaluate Skill Quality
+- Verify install count (prefer 1K+)
+- Check source reputation
+- Review skill documentation for relevance
+- Assess maintenance status (recent updates, issue activity)
+
+### Step 5: Delegate Installation
+- Create installation task for Boatswain
+- Specify exact package names and flags
+- Include verification requirements
+
+### Step 6: Verify and Document
+- Confirm skill is loaded and functional
+- Update project documentation with installed skills
+- Note skill usage in crew knowledge base
+
+---
+
+## Project-Level Skill Assessment
+
+When Captain analyzes a new project, follow this assessment protocol:
+
+### Technology Stack Analysis
+
+1. **Read package.json / requirements.txt / Cargo.toml**
+   - Identify frameworks (Next.js, Django, Rocket)
+   - Note testing libraries (Jest, pytest, cargo test)
+   - Find build tools (Webpack, setuptools, cargo)
+
+2. **Check configuration files**
+   - CI/CD configs (.github/workflows, GitLab CI)
+   - Linting/formatting (ESLint, Black, rustfmt)
+   - Environment files (.env.example, docker-compose)
+
+3. **Identify skill domains**
+
+| Technology Detected | Skill Domain to Search | Example Query |
+|---------------------|------------------------|---------------|
+| Next.js / React | Frontend framework patterns | `nextjs react` |
+| PostgreSQL / MongoDB | Database patterns | `database postgres` |
+| Stripe / Payment APIs | Payment integration | `stripe payment` |
+| Jest / Vitest | Testing best practices | `jest testing` |
+| Docker / Kubernetes | DevOps deployment | `docker kubernetes` |
+| Tailwind / CSS frameworks | Styling patterns | `tailwind css` |
+
+### Example: Next.js E-commerce Project
+
+**Analysis:**
+```
+Project: E-commerce platform
+Stack: Next.js 14, TypeScript, Stripe, PostgreSQL, Tailwind, Jest
+Current Skills: General coding, git workflow
+
+Gaps Identified:
+1. Next.js App Router patterns (new paradigm)
+2. Stripe payment integration (specialized domain)
+3. PostgreSQL schema design (database expertise)
+4. E-commerce security best practices
+```
+
+**Skill Search Queries:**
+```bash
+npx skills find nextjs app-router
+npx skills find stripe payment
+npx skills find postgresql database
+npx skills find ecommerce security
+```
+
+**Prioritization:**
+1. **Critical**: `stripe payment` (core functionality, high risk)
+2. **High**: `nextjs app-router` (architectural decisions)
+3. **Medium**: `postgresql database` (optimization)
+4. **Low**: `ecommerce security` (can be addressed incrementally)
+
+---
+
+## Task-Level Skill Selection
+
+For specific tasks, Captain uses this decision tree:
+
+### Task Analysis Protocol
+
+1. **Is this a domain-specific task?**
+   - NO → Proceed with general capabilities
+   - YES → Continue to step 2
+
+2. **Does crew have relevant skill installed?**
+   - YES → Use existing skill
+   - NO → Continue to step 3
+
+3. **Is there a high-quality skill available?**
+   - Search with specific query
+   - Verify quality (1K+ installs, reputable source)
+   - YES → Install and use
+   - NO → Proceed with general capabilities, document gap
+
+### Example: Testing Payment Module
+
+**Task:** "Add tests for Stripe payment webhook handler"
+
+**Analysis:**
+```
+Domain: Testing, Stripe, Webhooks
+Current Skills: Jest basics
+Gap: Stripe-specific testing patterns, webhook simulation
+
+Skill Search:
+npx skills find stripe testing webhook
+```
+
+**Decision:**
+- Found: `vercel-labs/agent-skills@stripe-testing` (12K installs)
+- Quality: High (Vercel source, good docs)
+- Action: Install before proceeding
+
+**Delegation:**
+```
+Task for Boatswain:
+- Install: npx skills add vercel-labs/agent-skills@stripe-testing -g -y
+- Verify: Check skill loads in environment
+- Report: Confirm installation success
+```
+
+### Decision Tree Diagram
+
+```
+Task Requires Specialized Knowledge?
+│
+├─ NO ──> Proceed with general capabilities
+│
+└─ YES
+    │
+    ├─ Skill Already Installed?
+    │   ├─ YES ──> Use existing skill
+    │   └─ NO
+    │       │
+    │       ├─ Search for Skills
+    │       │   │
+    │       │   ├─ High-Quality Skill Found? (1K+ installs, good source)
+    │       │   │   ├─ YES ──> Install & Use
+    │       │   │   └─ NO ──> Proceed with general capabilities
+    │       │   │           └─ Log gap in knowledge base
+    │       │   │
+    │       │   └─ No Skills Found
+    │       │       └─ Proceed with general capabilities
+    │       │           └─ Log gap in knowledge base
+```
+
+---
+
+## Integration with Crew Workflow
+
+### Captain Responsibilities
+
+1. **Identify skill needs** during project analysis and task planning
+2. **Delegate installation** to Boatswain with clear specifications
+3. **Verify installation** before proceeding with dependent tasks
+4. **Document skill usage** in project knowledge base
+5. **Monitor skill effectiveness** during task execution
+
+### Boatswain Responsibilities
+
+1. **Execute installation commands** as delegated by Captain
+2. **Verify installation success** by checking skill loads
+3. **Report results** back to Captain
+4. **Handle installation errors** following escalation protocol
+
+### Navigator Responsibilities
+
+1. **Suggest skills** during planning phase when identifying requirements
+2. **Include skill requirements** in mission specifications
+3. **Consider skill dependencies** when sequencing tasks
+
+### Quartermaster Responsibilities
+
+1. **Verify skill quality** independently if requested
+2. **Test skill functionality** before crew-wide adoption
+3. **Maintain skill inventory** for the project
+
+### Example Workflow: Project Initialization
+
+```
+1. Captain analyzes project → Identifies Next.js + Stripe stack
+2. Captain searches for skills → Finds relevant options
+3. Captain evaluates quality → Selects 2 high-quality skills
+4. Captain creates tasks in logbook:
+   - Task 1: Boatswain install nextjs-patterns skill
+   - Task 2: Boatswain install stripe-integration skill
+5. Boatswain executes installations
+6. Quartermaster verifies skills load correctly
+7. Captain updates knowledge base with installed skills
+8. Navigator proceeds with detailed planning using skill capabilities
+```
+
+---
+
+## Edge Cases and Error Handling
+
+### Case 1: No Skills Found
+
+**Scenario:** Search returns no results for identified gap.
+
+**Response:**
+1. Try alternative search terms
+2. Check leaderboard for similar domains
+3. Proceed with general capabilities
+4. Document gap in project knowledge base
+5. Consider creating custom skill if task is repeated frequently
+
+**Example:**
+```
+Search: npx skills find obscure-framework
+Result: No skills found
+
+Alternative queries:
+- npx skills find similar-framework
+- npx skills find framework category
+
+Fallback: Use general coding capabilities, document that
+"obscure-framework" expertise would improve quality.
+```
+
+### Case 2: Low-Quality Skills Only
+
+**Scenario:** Skills found but all have <100 installs or unknown sources.
+
+**Response:**
+1. Do not automatically install low-quality skills
+2. Assess if skill is truly necessary or "nice to have"
+3. For critical tasks: install with caution, verify thoroughly
+4. For non-critical tasks: proceed without skill
+5. Document the trade-off decision
+
+**Decision Tree:**
+```
+Skill Quality Low (<100 installs or unknown source)
+│
+├─ Task is Critical?
+│   ├─ YES ──> Install with extra verification
+│   │          └─ Test extensively before use
+│   └─ NO ──> Skip installation
+│              └─ Document limitation
+```
+
+### Case 3: Installation Failure
+
+**Scenario:** `npx skills add` command fails.
+
+**Response:**
+1. Check error message for specific issue
+2. Common fixes:
+   - Network issues → Retry with timeout
+   - Package not found → Verify package name
+   - Permission denied → Check file permissions
+3. Escalate to user if unresolvable
+4. Proceed with alternative approach if possible
+
+**Escalation Protocol:**
+```
+Level 1: Retry with verbose logging (npx skills add <pkg> --verbose)
+Level 2: Check skills.sh status page for outages
+Level 3: Report to user with error details and suggested alternatives
+```
+
+### Case 4: Skill Conflicts
+
+**Scenario:** New skill conflicts with existing skill or project setup.
+
+**Response:**
+1. Check skill documentation for known conflicts
+2. Test in isolation before project-wide use
+3. Consider using skill in specific contexts only
+4. Document conflict and resolution in knowledge base
+
+**Example:**
+```
+Conflict: new-testing-skill overrides Jest configuration
+
+Resolution:
+- Install skill but note conflict
+- Use skill for new test files only
+- Keep existing Jest config for legacy tests
+- Document: "new-testing-skill incompatible with current Jest setup"
+```
+
+### Case 5: Skill Becomes Outdated
+
+**Scenario:** Installed skill hasn't been updated in months.
+
+**Response:**
+1. Check for updates: `npx skills check`
+2. If update available: `npx skills update <skill-name>`
+3. If no updates and skill is critical:
+   - Search for alternative, maintained skills
+   - Consider forking and updating if open-source
+4. Document maintenance status in knowledge base
+
+---
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+| Security        | security, auth, encryption, owasp        |
+| Database        | database, postgresql, mongodb, redis     |
+| API Integration | api, rest, graphql, webhook              |
+
+---
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+4. **Combine domain + task**: "stripe webhook" is better than "webhook" alone
+5. **Include version for breaking changes**: "nextjs-14" vs "nextjs" for version-specific patterns
+
+---
+
+## Proactive Mode Best Practices
+
+### When to Auto-Install vs Ask
+
+**Auto-install (no user confirmation needed):**
+- Skills with 10K+ installs from reputable sources
+- Skills directly addressing critical capability gaps
+- Skills that are well-documented and maintained
+
+**Ask user first:**
+- Skills with <1K installs
+- Skills from unknown sources
+- Skills for non-critical enhancements
+- Skills that might conflict with existing setup
+
+### Documentation Requirements
+
+After proactive skill installation, always update:
+
+1. **Project knowledge base**: List installed skills with purpose
+2. **Logbook**: Record skill installation as completed task
+3. **Crew notes**: Document any special usage instructions
+
+### Example Logbook Entry
+
+```json
+{
+  "type": "task",
+  "id": "skill-install-001",
+  "description": "Install Stripe integration skill for payment module",
+  "assigned_to": "Boatswain",
+  "status": "completed",
+  "outcome": "Successfully installed vercel-labs/agent-skills@stripe-integration (12K installs). Verified skill loads and provides webhook testing patterns."
+}
+```
+
+---
+
+## Summary
+
+This dual-mode skill system enables:
+
+- **Reactive**: User-driven skill discovery for specific needs
+- **Proactive**: Captain-driven skill assessment for project optimization
+
+By combining both modes, the crew can efficiently extend capabilities based on both explicit user requests and autonomous analysis of project requirements.
+
+**Key Principles:**
+1. Always verify skill quality before installing
+2. Prioritize user experience (ask for non-critical installations)
+3. Document all skill installations and usage
+4. Handle errors gracefully with fallback plans
+5. Maintain skill inventory for project continuity