📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,255 @@
|
||||
---
|
||||
name: skills-discovery
|
||||
description: Find and evaluate community skills, plugins, and marketplaces. Use when searching for existing skills, evaluating safety, or when "find skill", "discover plugin", "community skills", or "marketplace" are mentioned.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
related-skills:
|
||||
- skills-dev
|
||||
- claude-plugins
|
||||
allowed-tools: Read WebFetch WebSearch Bash(gh:*)
|
||||
---
|
||||
|
||||
# Skills Discovery
|
||||
|
||||
Find community skills and plugins, evaluate quality and safety before use.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Searching for existing skills before building from scratch
|
||||
- Evaluating community plugins for safety and quality
|
||||
- Finding inspiration for skill design patterns
|
||||
- Auditing plugins before installation
|
||||
|
||||
NOT for: creating new skills (use skills-dev), validating your own skills (use skills-dev)
|
||||
|
||||
</when_to_use>
|
||||
|
||||
## Discovery Workflow
|
||||
|
||||
1. **Search** — Find candidates via GitHub topics or code search
|
||||
2. **Filter** — Apply quality heuristics to shortlist
|
||||
3. **Audit** — Security review before installation
|
||||
4. **Adapt** — Customize or extract patterns for your use
|
||||
|
||||
## GitHub Discovery
|
||||
|
||||
### Topic Pages
|
||||
|
||||
High-signal discovery starting points:
|
||||
|
||||
| Topic | Content | URL |
|
||||
|-------|---------|-----|
|
||||
| `claude-code-plugin` | Plugins | https://github.com/topics/claude-code-plugin |
|
||||
| `claude-code-plugin-marketplace` | Marketplaces | https://github.com/topics/claude-code-plugin-marketplace |
|
||||
| `claude-code-skills` | Skill packs | https://github.com/topics/claude-code-skills |
|
||||
| `claude-code-skill` | Individual skills | https://github.com/topics/claude-code-skill |
|
||||
|
||||
### Code Search Patterns
|
||||
|
||||
Precise searches for specific artifacts:
|
||||
|
||||
```text
|
||||
# Find SKILL.md files in .claude/skills paths
|
||||
filename:SKILL.md path:.claude/skills
|
||||
|
||||
# Find marketplace configurations
|
||||
".claude-plugin/marketplace.json"
|
||||
|
||||
# Find plugin manifests
|
||||
".claude-plugin/plugin.json"
|
||||
|
||||
# Find hook configurations
|
||||
"PreToolUse" AND hooks
|
||||
|
||||
# Find skills with specific features
|
||||
filename:SKILL.md "context: fork"
|
||||
filename:SKILL.md "allowed-tools"
|
||||
filename:SKILL.md "disable-model-invocation"
|
||||
```
|
||||
|
||||
### Recency Filters
|
||||
|
||||
Focus on actively maintained projects (adjust dates as needed):
|
||||
|
||||
```text
|
||||
# Updated in last 90 days (calculate: date -v-90d +%Y-%m-%d)
|
||||
pushed:>YYYY-MM-DD
|
||||
|
||||
# Updated since plugins era (Oct 2025+)
|
||||
pushed:>2025-10-01
|
||||
```
|
||||
|
||||
### Official Sources
|
||||
|
||||
| Source | Trust Level | Notes |
|
||||
|--------|-------------|-------|
|
||||
| anthropics/claude-plugins-official | High | Curated, reviewed |
|
||||
| agentskills/agentskills | High | Spec + reference skills |
|
||||
| platform.claude.com docs | High | Official patterns |
|
||||
| Community topics | Medium | Popularity ≠ quality |
|
||||
| "Awesome" lists | Low-Medium | Curated but not audited |
|
||||
|
||||
## Quality Heuristics
|
||||
|
||||
### Real Usage Signals
|
||||
|
||||
| Signal | Good | Suspicious |
|
||||
|--------|------|------------|
|
||||
| Updates | Recent commits, active issues | Stale for 6+ months |
|
||||
| Stars | Steady growth | Sudden spike (star farming) |
|
||||
| Issues/PRs | Open and being addressed | Many open, no responses |
|
||||
| Install docs | Uses official commands | "curl \| bash" installs |
|
||||
| Dependencies | Minimal, explained | Many unexplained deps |
|
||||
|
||||
### Content Quality
|
||||
|
||||
| Check | Good | Bad |
|
||||
|-------|------|-----|
|
||||
| Description | Clear WHAT + WHEN + TRIGGERS | Vague "helps with files" |
|
||||
| `allowed-tools` | Minimal, justified | Full tool access |
|
||||
| `disable-model-invocation` | Used for side effects | Missing for deploy/commit |
|
||||
| Scripts | Documented, minimal | Obfuscated, complex |
|
||||
| Hooks | Obvious purpose | Hidden network calls |
|
||||
|
||||
### Marketplaces
|
||||
|
||||
| Good Sign | Red Flag |
|
||||
|-----------|----------|
|
||||
| Version pinning | Floating branches |
|
||||
| Listed sources visible | Opaque references |
|
||||
| Clear update policy | Silent auto-updates |
|
||||
| Curated with criteria | "Everything goes" |
|
||||
|
||||
## Security Audit
|
||||
|
||||
### Threat Model
|
||||
|
||||
**Installing skills/plugins = running code.** Treat with same care as npm packages.
|
||||
|
||||
| Surface | Risk | Mitigation |
|
||||
|---------|------|------------|
|
||||
| Skills with Bash | Command execution | Review `allowed-tools` |
|
||||
| Hooks | Lifecycle interception | Review hook scripts |
|
||||
| MCP servers | External connections | Review endpoints |
|
||||
| Preprocessing `!` | Shell before thinking | Review commands |
|
||||
|
||||
### Audit Checklist
|
||||
|
||||
Before installing, review:
|
||||
|
||||
**For Skills:**
|
||||
- [ ] Read SKILL.md frontmatter (`allowed-tools`, `disable-model-invocation`)
|
||||
- [ ] Check for scripts/ directory — review any scripts
|
||||
- [ ] Search for `!` `` ` `` preprocessing commands
|
||||
- [ ] Verify no secrets/credentials in files
|
||||
|
||||
**For Plugins:**
|
||||
- [ ] Read .claude-plugin/plugin.json
|
||||
- [ ] Check for hooks/ — review hook scripts
|
||||
- [ ] Check for .mcp.json — review MCP endpoints
|
||||
- [ ] Review all referenced skill SKILL.md files
|
||||
|
||||
**For Hooks:**
|
||||
- [ ] Understand exit code semantics (0=allow, 2=block)
|
||||
- [ ] Check for network calls in hook scripts
|
||||
- [ ] Verify no data exfiltration patterns
|
||||
|
||||
### Sandboxing
|
||||
|
||||
When running untrusted skills:
|
||||
|
||||
1. **Restrict tools** — Start with minimal `allowed-tools`, expand as needed
|
||||
2. **Isolate context** — Use `context: fork` to limit blast radius
|
||||
3. **Block side effects** — Add `disable-model-invocation: true` initially
|
||||
4. **Monitor first run** — Watch tool calls on first execution
|
||||
|
||||
### Safe First Run
|
||||
|
||||
```markdown
|
||||
# Test skill in restricted mode:
|
||||
---
|
||||
name: untrusted-skill-test
|
||||
allowed-tools: Read, Grep, Glob # read-only first
|
||||
context: fork # isolated
|
||||
disable-model-invocation: true # explicit only
|
||||
---
|
||||
```
|
||||
|
||||
Expand permissions only after reviewing behavior.
|
||||
|
||||
## Use Case Catalog
|
||||
|
||||
Common skill categories with examples (for inspiration, not endorsement):
|
||||
|
||||
### Workflow Automation
|
||||
|
||||
| Pattern | What It Does | Key Features |
|
||||
|---------|--------------|--------------|
|
||||
| PR workflows | Summarize, review, update PRs | Preprocessing with `gh` |
|
||||
| Issue pipelines | Triage → implement → ship | Artifact-based state |
|
||||
| Release automation | Preflight → deploy → verify | Side-effect gates |
|
||||
|
||||
### Code Quality
|
||||
|
||||
| Pattern | What It Does | Key Features |
|
||||
|---------|--------------|--------------|
|
||||
| Spec gates | Verify scope before coding | Fork for clean analysis |
|
||||
| Adversarial review | Security-focused code review | Threat model in artifacts |
|
||||
| Refactor loops | Safe read-only explore first | Tool restrictions |
|
||||
|
||||
### Domain Skills
|
||||
|
||||
| Pattern | What It Does | Key Features |
|
||||
|---------|--------------|--------------|
|
||||
| Framework-specific | Rails, React, etc conventions | Nested skill discovery |
|
||||
| DB-aware | Schema injection for queries | Preprocessing with psql |
|
||||
| Platform integrations | Jira, Linear, GitHub | MCP or API wrappers |
|
||||
|
||||
### Safety & Guardrails
|
||||
|
||||
| Pattern | What It Does | Key Features |
|
||||
|---------|--------------|--------------|
|
||||
| Safety nets | Block irreversible operations | PreToolUse hooks |
|
||||
| Hardstops | Require human acknowledgment | Exit code blocking |
|
||||
| Test gates | Enforce tests before commit | Hook enforcement |
|
||||
|
||||
### Context Management
|
||||
|
||||
| Pattern | What It Does | Key Features |
|
||||
|---------|--------------|--------------|
|
||||
| Memory plugins | Persist across sessions | MCP-backed storage |
|
||||
| Context ledgers | Rolling state in files | Hook-driven updates |
|
||||
| Constraint files | Minimal "always load" context | Shared conventions |
|
||||
|
||||
## Extraction Patterns
|
||||
|
||||
When you find a useful skill, extract patterns rather than copying wholesale:
|
||||
|
||||
1. **Identify the pattern** — What makes it work?
|
||||
2. **Adapt to your context** — Match your conventions
|
||||
3. **Minimize scope** — Take only what you need
|
||||
4. **Document provenance** — Note where the pattern came from
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Verify recency (prefer active projects)
|
||||
- Review security surfaces before install
|
||||
- Start with restricted permissions
|
||||
- Document what you installed and why
|
||||
|
||||
NEVER:
|
||||
- Blindly install from unknown sources
|
||||
- Trust stars as quality signal
|
||||
- Run obfuscated scripts
|
||||
- Skip hook script review
|
||||
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
|
||||
- [discovery-patterns.md](references/discovery-patterns.md) — Detailed GitHub search patterns
|
||||
- [security-checklist.md](references/security-checklist.md) — Full audit checklist
|
||||
- [use-cases.md](references/use-cases.md) — Extended use case catalog
|
||||
|
||||
</references>
|
||||
+260
@@ -0,0 +1,260 @@
|
||||
# Discovery Patterns
|
||||
|
||||
Detailed GitHub search strategies for finding skills and plugins.
|
||||
|
||||
## Topic-Based Discovery
|
||||
|
||||
### Primary Topics
|
||||
|
||||
Navigate directly to GitHub topic pages:
|
||||
|
||||
| Topic | Description | URL |
|
||||
|-------|-------------|-----|
|
||||
| `claude-code-plugin` | Individual plugins | https://github.com/topics/claude-code-plugin |
|
||||
| `claude-code-plugin-marketplace` | Plugin marketplaces | https://github.com/topics/claude-code-plugin-marketplace |
|
||||
| `claude-code-skills` | Skill collections | https://github.com/topics/claude-code-skills |
|
||||
| `claude-code-skill` | Single skills | https://github.com/topics/claude-code-skill |
|
||||
|
||||
### Topic Page Analysis
|
||||
|
||||
On each topic page, use filters:
|
||||
|
||||
- **Sort by**: Recently updated (not Most stars)
|
||||
- **Language**: Filter if relevant (TypeScript, Python)
|
||||
- **Updated**: Last month/year
|
||||
|
||||
Note the topic card info:
|
||||
- Stars and forks
|
||||
- "Updated X days ago"
|
||||
- Short description
|
||||
|
||||
## Code Search Patterns
|
||||
|
||||
### Finding SKILL.md Files
|
||||
|
||||
```
|
||||
# Skills in standard location
|
||||
filename:SKILL.md path:.claude/skills
|
||||
|
||||
# Skills in home directory (tutorials, examples)
|
||||
filename:SKILL.md path:~/.claude/skills
|
||||
|
||||
# Any SKILL.md file
|
||||
filename:SKILL.md
|
||||
```
|
||||
|
||||
### Finding Plugin Manifests
|
||||
|
||||
```
|
||||
# Plugin configurations
|
||||
filename:plugin.json path:.claude-plugin
|
||||
|
||||
# Marketplace configurations
|
||||
filename:marketplace.json path:.claude-plugin
|
||||
|
||||
# Any plugin.json
|
||||
".claude-plugin/plugin.json"
|
||||
```
|
||||
|
||||
### Finding Hook Configurations
|
||||
|
||||
```
|
||||
# Hook definitions
|
||||
"PreToolUse" filename:hooks.json
|
||||
|
||||
# Hooks that block
|
||||
"exit 2" filename:hooks
|
||||
|
||||
# PostToolUse patterns
|
||||
"PostToolUse" AND "matcher"
|
||||
```
|
||||
|
||||
### Finding Specific Features
|
||||
|
||||
```
|
||||
# Skills with tool restrictions
|
||||
filename:SKILL.md "allowed-tools:"
|
||||
|
||||
# Skills with forked context
|
||||
filename:SKILL.md "context: fork"
|
||||
|
||||
# Skills with preprocessing
|
||||
filename:SKILL.md "`!"
|
||||
|
||||
# Side-effect-safe skills
|
||||
filename:SKILL.md "disable-model-invocation: true"
|
||||
|
||||
# Skills using specific agents
|
||||
filename:SKILL.md "agent: Explore"
|
||||
filename:SKILL.md "agent: Plan"
|
||||
```
|
||||
|
||||
### Finding Real-World Usage
|
||||
|
||||
```
|
||||
# Skills in major repos (indicates adoption)
|
||||
filename:SKILL.md org:pytorch
|
||||
filename:SKILL.md org:facebook
|
||||
filename:SKILL.md org:microsoft
|
||||
|
||||
# Skills with tests
|
||||
filename:SKILL.md path:test
|
||||
filename:SKILL.md path:__tests__
|
||||
```
|
||||
|
||||
## Recency Filters
|
||||
|
||||
GitHub search supports date filters. Calculate dates relative to today:
|
||||
|
||||
```bash
|
||||
# Get date for 30 days ago
|
||||
date -v-30d +%Y-%m-%d # macOS
|
||||
date -d "30 days ago" +%Y-%m-%d # Linux
|
||||
```
|
||||
|
||||
```
|
||||
# Updated in last 30 days (adjust date)
|
||||
pushed:>YYYY-MM-DD
|
||||
|
||||
# Updated in last 90 days (adjust date)
|
||||
pushed:>YYYY-MM-DD
|
||||
|
||||
# Updated since plugins announcement (Oct 2025)
|
||||
pushed:>2025-10-01
|
||||
|
||||
# Created recently (adjust date)
|
||||
created:>YYYY-MM-DD
|
||||
```
|
||||
|
||||
Combine with other searches:
|
||||
|
||||
```
|
||||
filename:SKILL.md pushed:>2025-10-01 "allowed-tools"
|
||||
```
|
||||
|
||||
## Quality Filters
|
||||
|
||||
### Activity Signals
|
||||
|
||||
```
|
||||
# Repos with issues
|
||||
filename:SKILL.md is:issue
|
||||
|
||||
# Repos with PRs
|
||||
filename:SKILL.md is:pr
|
||||
|
||||
# Archived repos (avoid)
|
||||
filename:SKILL.md NOT archived:true
|
||||
```
|
||||
|
||||
### Size Signals
|
||||
|
||||
```
|
||||
# Reasonable file sizes (not bloated)
|
||||
filename:SKILL.md size:<50000
|
||||
|
||||
# Multi-file skills (more complete)
|
||||
path:.claude/skills language:Markdown
|
||||
```
|
||||
|
||||
## CLI Alternatives
|
||||
|
||||
Using `gh` CLI for search:
|
||||
|
||||
```bash
|
||||
# Search code
|
||||
gh search code "filename:SKILL.md path:.claude/skills" --limit 50
|
||||
|
||||
# Search repos
|
||||
gh search repos "claude-code-skill" --sort updated --order desc
|
||||
|
||||
# Get repo details
|
||||
gh repo view owner/repo --json stargazersCount,pushedAt,description
|
||||
```
|
||||
|
||||
## Discovery Workflow
|
||||
|
||||
### 1. Broad Search
|
||||
|
||||
Start with topic pages, sorted by recent updates:
|
||||
- Note repos that appear across multiple searches
|
||||
- Check "Used by" if visible
|
||||
|
||||
### 2. Narrow by Feature
|
||||
|
||||
Use code search to find specific capabilities:
|
||||
```
|
||||
filename:SKILL.md "context: fork" pushed:>2025-10-01
|
||||
```
|
||||
|
||||
### 3. Verify Quality
|
||||
|
||||
For each candidate:
|
||||
```bash
|
||||
# Check activity
|
||||
gh repo view owner/repo --json pushedAt,openIssuesCount
|
||||
|
||||
# Check structure
|
||||
gh api repos/owner/repo/contents/.claude --jq '.[].name'
|
||||
```
|
||||
|
||||
### 4. Cross-Reference
|
||||
|
||||
Search for mentions:
|
||||
```
|
||||
"owner/repo" claude skill
|
||||
```
|
||||
|
||||
Check if referenced in:
|
||||
- Official docs
|
||||
- Awesome lists
|
||||
- Community discussions
|
||||
|
||||
## Bookmark-Worthy Sources
|
||||
|
||||
### Official
|
||||
|
||||
- [anthropics/claude-plugins-official](https://github.com/anthropics/claude-plugins-official) — Curated directory
|
||||
- [agentskills/agentskills](https://github.com/agentskills/agentskills) — Spec + reference skills
|
||||
- [Claude Code Docs](https://code.claude.com/docs/en/skills) — Official skill docs
|
||||
|
||||
### Community Directories
|
||||
|
||||
- Search for repos with "awesome-claude" in name
|
||||
- Check GitHub topics for curated lists
|
||||
|
||||
### Marketplaces
|
||||
|
||||
Search for marketplaces and evaluate before adding:
|
||||
```
|
||||
filename:marketplace.json path:.claude-plugin
|
||||
```
|
||||
|
||||
## Search Tips
|
||||
|
||||
### Escape Special Characters
|
||||
|
||||
```
|
||||
# Search for literal braces
|
||||
"interface\{\}"
|
||||
|
||||
# Search for backticks
|
||||
"`git status`"
|
||||
```
|
||||
|
||||
### Combine Patterns
|
||||
|
||||
```
|
||||
# Multiple requirements
|
||||
filename:SKILL.md "context: fork" "allowed-tools" pushed:>2025-10-01
|
||||
|
||||
# Exclude patterns
|
||||
filename:SKILL.md NOT "user-invocable: false"
|
||||
```
|
||||
|
||||
### Iterate
|
||||
|
||||
Start broad, then narrow:
|
||||
1. Topic search → get repo names
|
||||
2. Code search in promising repos → find specific skills
|
||||
3. Read and evaluate → decide on adoption
|
||||
+276
@@ -0,0 +1,276 @@
|
||||
# Security Checklist
|
||||
|
||||
Complete audit checklist before installing community skills, plugins, or marketplaces.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Threat Model](#threat-model)
|
||||
- [Pre-Installation Audit](#pre-installation-audit)
|
||||
- [Red Flags Checklist](#red-flags-checklist)
|
||||
- [Safe Installation Patterns](#safe-installation-patterns)
|
||||
- [Post-Installation Monitoring](#post-installation-monitoring)
|
||||
- [Marketplace-Specific Checks](#marketplace-specific-checks)
|
||||
- [Recovery Procedures](#recovery-procedures)
|
||||
- [Template: Audit Report](#template-audit-report)
|
||||
|
||||
---
|
||||
|
||||
## Threat Model
|
||||
|
||||
**Core principle**: Installing skills/plugins = running code. Treat with same care as npm packages.
|
||||
|
||||
### Attack Surfaces
|
||||
|
||||
| Surface | Risk Level | Attack Vector |
|
||||
|---------|------------|---------------|
|
||||
| `allowed-tools: Bash(*)` | High | Arbitrary command execution |
|
||||
| Hook scripts | High | Lifecycle interception, data exfiltration |
|
||||
| MCP servers | High | External network connections |
|
||||
| Preprocessing `!` | Medium | Shell commands before model reasoning |
|
||||
| Scripts in scripts/ | Medium | Executed during skill operation |
|
||||
| Write/Edit permissions | Medium | File system modifications |
|
||||
|
||||
### Threat Categories
|
||||
|
||||
| Threat | Example | Detection |
|
||||
|--------|---------|-----------|
|
||||
| Data exfiltration | Hook sends files to external server | Review hook network calls |
|
||||
| Credential theft | Skill reads .env and logs it | Check for secret file access |
|
||||
| Arbitrary execution | Bash(*) with no restriction | Review allowed-tools |
|
||||
| Persistent access | Creates cron job or daemon | Check for persistence patterns |
|
||||
| Supply chain | Marketplace references malicious plugins | Verify all referenced sources |
|
||||
|
||||
## Pre-Installation Audit
|
||||
|
||||
### Step 1: Repository Signals
|
||||
|
||||
| Check | Good Sign | Red Flag |
|
||||
|-------|-----------|----------|
|
||||
| Commits | Steady history | Single commit dump |
|
||||
| Contributors | Multiple contributors | Single anonymous author |
|
||||
| Stars | Organic growth | Sudden spike |
|
||||
| Issues | Active engagement | Many open, no response |
|
||||
| Updates | Recent activity | Stale for 6+ months |
|
||||
|
||||
```bash
|
||||
# Quick repo check
|
||||
gh repo view owner/repo --json stargazersCount,pushedAt,openIssuesCount,description
|
||||
```
|
||||
|
||||
### Step 2: Skill Audit (for each SKILL.md)
|
||||
|
||||
```markdown
|
||||
# Open SKILL.md and check:
|
||||
|
||||
## Frontmatter Review
|
||||
- [ ] `allowed-tools` is minimal and justified
|
||||
- [ ] `disable-model-invocation: true` for side-effect skills
|
||||
- [ ] `context: fork` used appropriately (analysis = fork)
|
||||
- [ ] No suspicious combinations (e.g., Bash(*) + Write + no restrictions)
|
||||
|
||||
## Content Review
|
||||
- [ ] Instructions are clear and purposeful
|
||||
- [ ] No hidden commands in prose
|
||||
- [ ] Preprocessing `!` commands are obvious and safe
|
||||
- [ ] No instructions to disable security features
|
||||
```
|
||||
|
||||
### Step 3: Script Audit (for scripts/ directory)
|
||||
|
||||
```markdown
|
||||
# For each script:
|
||||
|
||||
- [ ] Understand what it does (no obfuscation)
|
||||
- [ ] No network calls without clear purpose
|
||||
- [ ] No reading of credentials/secrets
|
||||
- [ ] No writing outside project directory
|
||||
- [ ] No system modifications (cron, daemons, etc.)
|
||||
- [ ] Dependencies are minimal and known
|
||||
```
|
||||
|
||||
### Step 4: Hook Audit (for hooks.json and hook scripts)
|
||||
|
||||
```markdown
|
||||
# Hook configuration review:
|
||||
|
||||
- [ ] Understand each hook's trigger (PreToolUse, PostToolUse, etc.)
|
||||
- [ ] Matchers are scoped appropriately
|
||||
- [ ] Exit codes make sense (0=allow, 2=block)
|
||||
|
||||
# Hook script review:
|
||||
|
||||
- [ ] No network calls (curl, wget, fetch)
|
||||
- [ ] No data exfiltration patterns
|
||||
- [ ] No writes to unexpected locations
|
||||
- [ ] No process spawning or backgrounding
|
||||
- [ ] Clear, readable logic
|
||||
```
|
||||
|
||||
### Step 5: MCP Audit (for .mcp.json)
|
||||
|
||||
```markdown
|
||||
# MCP configuration review:
|
||||
|
||||
- [ ] Understand each server's purpose
|
||||
- [ ] Endpoints are to trusted services
|
||||
- [ ] No unexpected permissions requested
|
||||
- [ ] No persistent connections to unknown hosts
|
||||
```
|
||||
|
||||
### Step 6: Plugin Audit (for plugin.json)
|
||||
|
||||
```markdown
|
||||
# Plugin manifest review:
|
||||
|
||||
- [ ] All referenced skills pass Step 2
|
||||
- [ ] All hooks pass Step 4
|
||||
- [ ] All MCP servers pass Step 5
|
||||
- [ ] No unexpected file references
|
||||
- [ ] Version pinning is reasonable
|
||||
```
|
||||
|
||||
## Red Flags Checklist
|
||||
|
||||
Stop and investigate if you see:
|
||||
|
||||
```markdown
|
||||
# Immediate red flags:
|
||||
|
||||
- [ ] Obfuscated code (base64, minified, packed)
|
||||
- [ ] "curl | bash" install patterns
|
||||
- [ ] Requests to disable sandboxing
|
||||
- [ ] Writes to system directories (/etc, /usr)
|
||||
- [ ] Access to SSH keys, AWS credentials, etc.
|
||||
- [ ] Unexplained network endpoints
|
||||
- [ ] Process backgrounding or persistence
|
||||
- [ ] Encoding/decoding without clear purpose
|
||||
```
|
||||
|
||||
## Safe Installation Patterns
|
||||
|
||||
### Restricted First Run
|
||||
|
||||
```yaml
|
||||
# Override untrusted skill with restrictions:
|
||||
---
|
||||
name: test-untrusted
|
||||
allowed-tools: Read, Grep, Glob # Read-only
|
||||
context: fork # Isolated
|
||||
disable-model-invocation: true # No auto-trigger
|
||||
---
|
||||
|
||||
# Test the skill with restricted permissions first
|
||||
```
|
||||
|
||||
### Gradual Permission Expansion
|
||||
|
||||
1. Start with read-only tools
|
||||
2. Monitor tool calls on first runs
|
||||
3. Add Write/Edit after behavior verified
|
||||
4. Add Bash only for specific commands
|
||||
5. Never grant Bash(*) to untrusted code
|
||||
|
||||
### Sandbox Isolation
|
||||
|
||||
```markdown
|
||||
# When testing untrusted skills:
|
||||
|
||||
1. Use a separate project directory
|
||||
2. No access to home directory secrets
|
||||
3. Network isolation if possible
|
||||
4. Monitor file system changes
|
||||
5. Review all tool calls
|
||||
```
|
||||
|
||||
## Post-Installation Monitoring
|
||||
|
||||
After installing, watch for:
|
||||
|
||||
```markdown
|
||||
# First few uses:
|
||||
|
||||
- [ ] Tool calls match expected behavior
|
||||
- [ ] No unexpected file access
|
||||
- [ ] No network calls (unless expected)
|
||||
- [ ] Output makes sense for inputs
|
||||
- [ ] No persistent changes to environment
|
||||
```
|
||||
|
||||
## Marketplace-Specific Checks
|
||||
|
||||
When adding a marketplace:
|
||||
|
||||
```markdown
|
||||
# Marketplace audit:
|
||||
|
||||
- [ ] Source is known/trusted
|
||||
- [ ] Referenced plugins are version-pinned
|
||||
- [ ] Update mechanism is transparent
|
||||
- [ ] No auto-execution on add
|
||||
- [ ] Each referenced plugin passes full audit
|
||||
```
|
||||
|
||||
## Recovery Procedures
|
||||
|
||||
If you installed something suspicious:
|
||||
|
||||
```markdown
|
||||
# Immediate steps:
|
||||
|
||||
1. Remove the skill/plugin: /plugin uninstall <name>
|
||||
2. Check for persistence: crontab -l, launchctl list
|
||||
3. Review recent file changes: git status, find . -mmin -60
|
||||
4. Rotate any credentials that might be exposed
|
||||
5. Review shell history for executed commands
|
||||
|
||||
# If compromise suspected:
|
||||
|
||||
1. Revoke API keys/tokens
|
||||
2. Change passwords
|
||||
3. Notify team if shared environment
|
||||
4. Document what was installed and when
|
||||
```
|
||||
|
||||
## Template: Audit Report
|
||||
|
||||
```markdown
|
||||
# Skill/Plugin Audit: {name}
|
||||
|
||||
**Source**: {repo URL}
|
||||
**Auditor**: {your name}
|
||||
**Date**: {date}
|
||||
|
||||
## Repository Signals
|
||||
- Stars: {n}
|
||||
- Last updated: {date}
|
||||
- Open issues: {n}
|
||||
- Contributors: {n}
|
||||
|
||||
## Security Assessment
|
||||
|
||||
### Skills Reviewed
|
||||
- [ ] {skill-1}: {notes}
|
||||
- [ ] {skill-2}: {notes}
|
||||
|
||||
### Hooks Reviewed
|
||||
- [ ] {hook-1}: {notes}
|
||||
|
||||
### Scripts Reviewed
|
||||
- [ ] {script-1}: {notes}
|
||||
|
||||
### Red Flags Found
|
||||
- {none | list}
|
||||
|
||||
## Verdict
|
||||
- [ ] Safe to install
|
||||
- [ ] Safe with restrictions: {specify}
|
||||
- [ ] Do not install: {reason}
|
||||
|
||||
## Restrictions Applied
|
||||
```yaml
|
||||
allowed-tools: {restricted set}
|
||||
```
|
||||
|
||||
## Notes
|
||||
{additional observations}
|
||||
```
|
||||
@@ -0,0 +1,240 @@
|
||||
# Use Case Catalog
|
||||
|
||||
Condensed catalog of skill and plugin patterns for inspiration. Categories reflect common community implementations.
|
||||
|
||||
## Workflow Automation
|
||||
|
||||
### PR & Code Review
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| PR Summary | Preprocessing with `gh` for live context | `!gh pr diff` injects changes before analysis |
|
||||
| Review Notes | Forked context for clean analysis | `context: fork` prevents history pollution |
|
||||
| Commit Message | Arguments drive behavior | `$ARGUMENTS` for issue number or description |
|
||||
|
||||
**Stealable idea**: Deterministic preprocessing replaces tool calls with cached-at-invoke snapshots.
|
||||
|
||||
### Issue Pipelines
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Triage → Plan → Implement | Artifact-based state handoff | Each step reads previous, writes own artifact |
|
||||
| Acceptance criteria | Gates between steps | Next step requires previous artifact exists |
|
||||
| Rollback plans | Plan artifacts include undo | Always document how to revert |
|
||||
|
||||
**Stealable idea**: State lives in files, not conversation. Survives compaction.
|
||||
|
||||
### Release Automation
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Preflight gates | Hooks enforce tests | PreToolUse blocks deploy if tests red |
|
||||
| Manual deploy | User-invoked only | `disable-model-invocation: true` |
|
||||
| Post-deploy verify | Deterministic checks | Health endpoints, error counts |
|
||||
|
||||
**Stealable idea**: "Guardrails sandwich" — hooks before, checks after, agent in middle.
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Spec Gates
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Write spec first | Forked deliberation | `context: fork`, `agent: Plan` |
|
||||
| Threat model | Security in spec stage | Include "where could data leak?" |
|
||||
| Scope detection | Catch prompt injection | Check for scope creep in spec |
|
||||
|
||||
**Stealable idea**: Institutionalize paranoia before code stage, not after.
|
||||
|
||||
### Safe Refactoring
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Read-only first | Explore before mutate | `allowed-tools: Read, Grep, Glob` |
|
||||
| Refactor plan | Document changes before making | Artifact gates execution |
|
||||
| Tests as gates | No refactor without green tests | Hook enforcement |
|
||||
|
||||
**Stealable idea**: Separate exploration from execution. Cheaper to plan wrong than code wrong.
|
||||
|
||||
### Adversarial Review
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Multiple perspectives | Council pattern | Run security + perf + UX reviewers |
|
||||
| Merge reviews | Single decision artifact | Synthesize diverse findings |
|
||||
| Dissent tracking | Document disagreements | Review notes include opposing views |
|
||||
|
||||
**Stealable idea**: Force diverse failure modes. One perspective misses things.
|
||||
|
||||
## Domain Skills
|
||||
|
||||
### Framework-Specific
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Rails conventions | Package per framework | Skills encode framework idioms |
|
||||
| React patterns | Component helpers | Stack-specific best practices |
|
||||
| Nested discovery | Package-local skills | `.claude/skills` in each package |
|
||||
|
||||
**Stealable idea**: Skills encode "how we do X here" as executable documentation.
|
||||
|
||||
### DB-Aware
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Schema injection | Preprocessing with psql | `!psql -c "\\d table"` |
|
||||
| Query validation | Explain before execute | Read-only analysis of queries |
|
||||
| Migration planning | Document before alter | Artifact for migration spec |
|
||||
|
||||
**Stealable idea**: Inject schema deterministically so every query is structure-aware.
|
||||
|
||||
### Platform Integrations
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Jira/Linear | Issue context injection | Preprocessing or MCP |
|
||||
| GitHub | `gh` CLI preprocessing | `!gh` for live state |
|
||||
| Pinecone/search | MCP for external index | Offload heavy operations |
|
||||
|
||||
**Stealable idea**: Use preprocessing for read operations, MCP for stateful services.
|
||||
|
||||
## Safety & Guardrails
|
||||
|
||||
### Safety Nets
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Dangerous command block | PreToolUse hooks | Exit code 2 blocks tool |
|
||||
| Irreversible detection | Regex on commands | Match `rm -rf`, `push --force` |
|
||||
| File protection | Path-based blocking | Prevent writes to sensitive dirs |
|
||||
|
||||
**Stealable idea**: Guardrails outside the LLM, not inside prompts.
|
||||
|
||||
### Test Gates
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Commit requires tests | Hook blocks git commit | PreToolUse on `Bash(git commit)` |
|
||||
| File flag pattern | Tests create flag file | Hook checks for flag existence |
|
||||
| CI/CD integration | Status checks | Query CI status before merge |
|
||||
|
||||
**Stealable idea**: "Run tests" as mechanical enforcement, not polite suggestion.
|
||||
|
||||
### Human Acknowledgment
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Hardstop before deploy | Explicit invocation | `disable-model-invocation: true` |
|
||||
| Checkpoint artifacts | Review before proceed | Artifacts serve as gates |
|
||||
| Decision logging | Document what was approved | Append decisions to context.md |
|
||||
|
||||
**Stealable idea**: High-stakes actions require explicit human trigger.
|
||||
|
||||
## Context Management
|
||||
|
||||
### Memory Plugins
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Cross-session state | MCP-backed storage | Store/retrieve outside context window |
|
||||
| Selective loading | Query for relevant memories | Only load what current task needs |
|
||||
| Structured memory | Typed storage schemas | Not just blobs, queryable facts |
|
||||
|
||||
**Stealable idea**: Memory belongs in persistent store, loaded selectively.
|
||||
|
||||
### Context Ledgers
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Rolling state files | Hooks update on changes | PostToolUse updates context.md |
|
||||
| Decision logs | Append-only history | Never delete, only append |
|
||||
| Minimal constraints | Small always-loaded file | constraints.md with invariants |
|
||||
|
||||
**Stealable idea**: Small files that always load, volatile state in artifacts.
|
||||
|
||||
### Preprocessing for Context
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Git state | `!git status` | Snapshot at skill load |
|
||||
| Environment info | `!node --version` | Runtime context |
|
||||
| Schema dumps | `!psql -c "\\d"` | Structure without tool calls |
|
||||
|
||||
**Stealable idea**: Deterministic context injection is cheaper than tool calls.
|
||||
|
||||
## Multi-Agent Orchestration
|
||||
|
||||
### Subagent Patterns
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Explore → implement | Read-only then mutate | Different agent per stage |
|
||||
| Parallel analysis | Concurrent forked skills | Multiple `context: fork` runs |
|
||||
| Result merging | Synthesis skill | Merge multiple artifact outputs |
|
||||
|
||||
**Stealable idea**: Split work by capability, not just by step.
|
||||
|
||||
### Council Pattern
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Diverse reviewers | Security + perf + UX | Each in forked context |
|
||||
| Forced disagreement | Different failure modes | Reviewers can't see each other |
|
||||
| Unified decision | Merge with conflicts noted | Decision artifact acknowledges dissent |
|
||||
|
||||
**Stealable idea**: Force diverse perspectives by running separate analyses.
|
||||
|
||||
### Dispatcher Pattern
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Task routing | Match task to specialist | Orchestrator skill selects agent |
|
||||
| Capability matching | Agent per domain | DB agent, frontend agent, etc. |
|
||||
| Handoff artifacts | Standard interface | All agents write to artifacts/ |
|
||||
|
||||
**Stealable idea**: Orchestrator stays lean, specialists do heavy work.
|
||||
|
||||
## Debugging & Incidents
|
||||
|
||||
### Evidence Gathering
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Deterministic capture | Preprocessing logs | `!tail -100 /var/log/app.log` |
|
||||
| State snapshot | Git + system state | Multiple preprocessing commands |
|
||||
| Timeline construction | Chronological evidence | Artifact structures timeline |
|
||||
|
||||
**Stealable idea**: Gather evidence deterministically before forming hypotheses.
|
||||
|
||||
### Hypothesis Testing
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Ranked hypotheses | Likelihood ordering | Artifact lists hypotheses by probability |
|
||||
| Evidence mapping | What supports/refutes | Link evidence to hypotheses |
|
||||
| Investigation steps | Falsifiable tests | Clear next steps to confirm/reject |
|
||||
|
||||
**Stealable idea**: Systematic debugging beats guessing. Evidence first.
|
||||
|
||||
### Postmortems
|
||||
|
||||
| Pattern | Key Insight | Implementation |
|
||||
|---------|-------------|----------------|
|
||||
| Artifact-driven | All incidents leave trail | Read all incident artifacts |
|
||||
| Action items | Tracked in artifact | Postmortem includes todos |
|
||||
| Pattern extraction | Learn for next time | Codify if pattern repeats |
|
||||
|
||||
**Stealable idea**: Incidents produce artifacts that inform future prevention.
|
||||
|
||||
## Key Patterns Summary
|
||||
|
||||
| Pattern | One-Line Summary |
|
||||
|---------|------------------|
|
||||
| Preprocessing | Shell commands inject context before model thinks |
|
||||
| Artifacts | Files pass state between skills |
|
||||
| Fork vs Inherit | Analysis forks, implementation inherits |
|
||||
| Gates | Artifacts as prerequisites for next step |
|
||||
| Side-effect protection | `disable-model-invocation: true` |
|
||||
| Tool restriction | `allowed-tools` minimal per skill |
|
||||
| Council | Multiple perspectives in parallel forks |
|
||||
| Guardrails sandwich | Hooks before + after, agent in middle |
|
||||
Reference in New Issue
Block a user