@anysiteio/agent-skills 1.0.1 → 1.3.0

package/skills/anysite-cli/references/llm-reference.md

@@ -0,0 +1,274 @@
+# LLM Analysis Reference
+
+## Setup
+
+```bash
+anysite llm setup
+```
+
+Interactive configuration: selects provider (`openai` or `anthropic`), API key environment variable, default model, and optionally tests the connection. Writes to `~/.anysite/config.yaml` under the `llm:` key.
+
+### Configuration Format
+
+```yaml
+llm:
+  default_provider: openai
+  providers:
+    openai:
+      provider: openai
+      api_key_env: OPENAI_API_KEY
+      default_model: gpt-4.1-mini
+    anthropic:
+      provider: anthropic
+      api_key_env: ANTHROPIC_API_KEY
+      default_model: claude-sonnet-4-5-20250514
+  cache_enabled: true
+  default_temperature: 0.0
+  default_max_tokens: 4096
+  rate_limit: "50/m"
+```
+
+### Provider Support
+
+| Provider | SDK | Structured Output | Default Model |
+|----------|-----|-------------------|---------------|
+| OpenAI | `openai` (AsyncOpenAI) | JSON Schema via `response_format` | `gpt-4.1-mini` |
+| Anthropic | `anthropic` (AsyncAnthropic) | System-prompt with JSON schema instruction | `claude-sonnet-4-5-20250514` |
+
+## Commands
+
+### `anysite llm summarize`
+
+Summarize each record in a dataset source.
+
+```bash
+anysite llm summarize <dataset.yaml> --source <source_id> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source, -s` | Source to summarize (required) |
+| `--max-length` | Max words in summary (default: 100) |
+| `--output-column` | Column name for summary (default: `summary`) |
+| `--prompt` | Custom prompt override |
+| `--prompt-file` | Read prompt from file |
+| `--dry-run` | Show prompt without calling LLM |
+
+### `anysite llm classify`
+
+Classify records into categories.
+
+```bash
+anysite llm classify <dataset.yaml> --source <source_id> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source, -s` | Source to classify (required) |
+| `--categories, -c` | Comma-separated categories (auto-detects if omitted) |
+| `--multi` | Allow multiple categories per record |
+| `--output-column` | Column name for category (default: `category`) |
+| `--prompt` | Custom prompt override |
+| `--prompt-file` | Read prompt from file |
+| `--dry-run` | Show prompt without calling LLM |
+
+When `--categories` is omitted, the classifier auto-detects 3-7 categories from the first 20 records.
+
+### `anysite llm enrich`
+
+Enrich records with LLM-extracted attributes.
+
+```bash
+anysite llm enrich <dataset.yaml> --source <source_id> --add <spec> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source, -s` | Source to enrich (required) |
+| `--add` | Field spec: `name:type_or_values` (repeatable, at least one required) |
+| `--prompt` | Custom prompt override |
+| `--prompt-file` | Read prompt from file |
+| `--dry-run` | Show prompt without calling LLM |
+
+**Field spec formats:**
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Enum | `sentiment:positive/negative/neutral` | Constrained to listed values |
+| Type | `language:string` | Free-form string |
+| Range | `quality_score:1-10` | Integer value |
+| Boolean | `is_technical:boolean` | True/false |
+| Number | `relevance:number` | Floating point |
+
+### `anysite llm generate`
+
+Generate text for each record using a custom prompt.
+
+```bash
+anysite llm generate <dataset.yaml> --source <source_id> --prompt <template> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source, -s` | Source to process (required) |
+| `--prompt` | Prompt with `{field}` placeholders (required unless `--prompt-file`) |
+| `--prompt-file` | Read prompt from file |
+| `--output-column` | Column name for generated text (default: `text`) |
+| `--dry-run` | Show prompt without calling LLM |
+
+The prompt template supports `{field_name}` placeholders that are replaced with record values. Example: `"Write a bio for {name} who works as {headline}"`.
+
+Default temperature is 0.7 (higher than other commands).
+
+### `anysite llm match`
+
+Match records between two dataset sources.
+
+```bash
+anysite llm match <dataset.yaml> --source-a <id> --source-b <id> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source-a` | First source (required) |
+| `--source-b` | Second source (required) |
+| `--fields-a` | Fields from source A to include |
+| `--fields-b` | Fields from source B to include |
+| `--top-k` | Max matches per source-a record (default: 3) |
+| `--threshold` | Min match score 0.0-1.0 (default: 0.5) |
+| `--prompt` | Custom prompt override |
+| `--prompt-file` | Read prompt from file |
+| `--dry-run` | Show prompt without calling LLM |
+
+Processes each source-a record against batches of 10 source-b records. Returns matches with score and reason.
+
+### `anysite llm deduplicate`
+
+Find semantic duplicates in a dataset source.
+
+```bash
+anysite llm deduplicate <dataset.yaml> --source <source_id> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source, -s` | Source to deduplicate (required) |
+| `--key, -k` | Field for blocking (grouping similar records) (default: `name`) |
+| `--threshold` | Min confidence for duplicate (default: 0.8) |
+| `--prompt` | Custom prompt override |
+| `--prompt-file` | Read prompt from file |
+| `--dry-run` | Show prompt without calling LLM |
+
+Uses a blocking pass (first 3 chars of key field) to group candidate duplicates before LLM evaluation.
+
+### `anysite llm cache-stats`
+
+Show LLM cache statistics (entry count, total input/output tokens).
+
+```bash
+anysite llm cache-stats
+anysite llm cache-stats --json    # Machine-readable JSON output
+```
+
+### `anysite llm cache-clear`
+
+Clear all cached LLM responses.
+
+```bash
+anysite llm cache-clear
+anysite llm cache-clear --json    # Machine-readable JSON output
+```
+
+## Common Options
+
+These options are shared across `summarize`, `classify`, `enrich`, `generate`, `match`, and `deduplicate`:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--provider` | LLM provider name | From config |
+| `--model` | Model ID override | From config |
+| `--parallel, -j` | Concurrent LLM calls | 5 |
+| `--rate-limit` | Rate limit (e.g., `"50/m"`, `"10/s"`) | From config |
+| `--temperature` | LLM temperature | 0.0 (0.7 for generate) |
+| `--max-tokens` | Max response tokens | 4096 |
+| `--no-cache` | Skip cache lookup | false |
+| `--format, -f` | Output format: json/jsonl/csv/table | json |
+| `--output, -o` | Write results to file | stdout |
+| `--fields` | Record fields to include in LLM prompt | All fields |
+| `--quiet, -q` | Suppress progress/stats output | false |
+| `--dry-run` | Show prompt without calling LLM | false |
+| `--prompt` | Custom prompt template | Built-in |
+| `--prompt-file` | Read prompt from file | - |
+
+## Prompt System
+
+### Built-in Prompts
+
+| Key | Used by | Description |
+|-----|---------|-------------|
+| `summarize` | `summarize` | Summarize record in N words |
+| `classify` | `classify` | Classify records into categories |
+| `classify_auto_detect` | `classify` (no categories) | Auto-detect categories from sample |
+| `match` | `match` | Rank candidates by relevance |
+| `deduplicate` | `deduplicate` | Identify semantic duplicates |
+| `enrich` | `enrich` | Extract specified attributes |
+
+### Custom Prompts
+
+Use `--prompt` for inline templates or `--prompt-file` to read from a file.
+
+Template variables:
+- `{record}` — formatted record (all non-underscore fields)
+- `{records}` — formatted batch of records with indices
+- `{field_name}` — individual record field value
+- Command-specific variables: `{max_length}`, `{categories}`, `{field_descriptions}`, `{source_a_name}`, `{source_b_name}`, etc.
+
+### Field Filtering
+
+`--fields "name,headline,location"` restricts which record fields are sent to the LLM. Supports dot-notation for nested fields (e.g., `urn.value`).
+
+## Cache System
+
+SQLite database at `~/.anysite/llm_cache.db` with WAL mode. Cache keys are SHA256 hashes of `{provider}:{system_prompt+user_prompt}:{input_data}`.
+
+Disable per-command with `--no-cache`. Disable globally by setting `cache_enabled: false` in config.
+
+## Examples
+
+```bash
+# Classify LinkedIn posts by sentiment
+anysite llm classify dataset.yaml --source posts \
+  --categories "positive,negative,neutral" \
+  --fields "text,title" --format table --output sentiment.csv
+
+# Summarize company profiles
+anysite llm summarize dataset.yaml --source companies \
+  --fields "name,description,industry" --max-length 50 --format table
+
+# Enrich profiles with multiple attributes
+anysite llm enrich dataset.yaml --source profiles \
+  --add "seniority:junior/mid/senior/executive" \
+  --add "department:string" \
+  --add "is_technical:boolean" \
+  --format csv --output enriched.csv
+
+# Generate personalized messages
+anysite llm generate dataset.yaml --source profiles \
+  --prompt "Write a cold outreach message for {name}, {headline} at {company}" \
+  --temperature 0.7 --model gpt-4.1
+
+# Match people to companies
+anysite llm match dataset.yaml --source-a profiles --source-b companies \
+  --fields-a "name,headline,skills" --fields-b "name,industry,description" \
+  --top-k 3 --threshold 0.6
+
+# Find duplicate profiles
+anysite llm deduplicate dataset.yaml --source profiles \
+  --key name --threshold 0.8 --fields "name,headline,location"
+
+# Preview prompt without calling LLM
+anysite llm classify dataset.yaml --source posts --dry-run
+
+# Use a custom prompt from file
+anysite llm generate dataset.yaml --source profiles --prompt-file my_prompt.txt
+```

package/skills/skill-audit/README.md

@@ -0,0 +1,287 @@
+# Skill Audit
+
+Static security auditor for Claude Code skills, commands, and plugins. Detects dangerous patterns — excessive permissions, hooks, prompt injection, credential access, privilege escalation — before you enable a skill.
+
+**Developer:** Anysite Skills Contributors
+
+## Overview
+
+The Skill Audit skill performs read-only static security analysis of Claude Code skills, commands, and plugins. It analyzes SKILL.md files, supporting scripts, and hooks to identify security risks before installation.
+
+Works with both local files and remote GitHub repositories.
+
+## Installation
+
+### Prerequisites
+
+- **Claude Code** - Version with skill support enabled
+- **Anysite Skills Marketplace** - Already added if you're viewing this
+
+### Install from Marketplace
+
+```bash
+# Add the marketplace (if not already added)
+/plugin marketplace add https://github.com/anysiteio/agent-skills
+
+# Install the skill
+/plugin install skill-audit@anysite-skills
+```
+
+### Permissions
+
+The skill requires these permissions (automatically granted during installation):
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Skill(skill-audit)",
+      "Skill(skill-audit:*)"
+    ]
+  }
+}
+```
+
+For stricter WebFetch domain enforcement (recommended):
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Skill(skill-audit)",
+      "Skill(skill-audit:*)",
+      "WebFetch(domain:api.github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ]
+  }
+}
+```
+
+## Usage
+
+### Quick Start
+
+Once installed, invoke the skill to audit targets:
+
+```bash
+# Audit a specific skill directory
+/skill-audit .claude/skills/my-skill
+
+# Audit a specific command file
+/skill-audit .claude/commands/deploy.md
+
+# Audit a skill by name (searches .claude/skills/ and .claude/commands/)
+/skill-audit my-skill
+
+# Audit ALL skills and commands in the current project
+/skill-audit
+```
+
+### Remote Audit (GitHub)
+
+Audit skills from GitHub before installing them:
+
+```bash
+# Audit a GitHub repository
+/skill-audit https://github.com/user/repo
+
+# Audit a specific directory on GitHub
+/skill-audit https://github.com/user/repo/tree/main/.claude/skills/my-skill
+
+# Audit a single file from GitHub
+/skill-audit https://github.com/user/repo/blob/main/.claude/commands/deploy.md
+```
+
+## What It Checks
+
+The auditor performs a comprehensive 5-phase static analysis:
+
+### Analysis Phases
+
+| Phase | What It Analyzes |
+|-------|------------------|
+| **Discovery** | Inventories all files in the skill/plugin directory, detects plugin structure |
+| **Frontmatter** | Checks `allowed-tools`, hooks, permissions, invocation settings |
+| **Body Content** | Scans for dangerous tool references, settings manipulation, injection patterns, sensitive file access |
+| **Supporting Files** | Examines scripts for network egress, credential access, code execution, persistence |
+| **Hooks** | Detects hook definitions or installations, classifies by risk level |
+
+### Detection Rules
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| **SKL-001a** | Medium | Hooks present in skill (require manual review) |
+| **SKL-001b** | Critical | Hooks with dangerous patterns (network, credentials, persistence) |
+| **SKL-002** | Critical/High | Prompt injection or dynamic injection patterns (`!` + backticks, `$(...)`) |
+| **SKL-003** | High | Bash/WebFetch/broad wildcards in `allowed-tools` |
+| **SKL-004** | Medium/High | Missing `disable-model-invocation` on side-effect skills |
+| **SKL-005** | High | Dangerous patterns in supporting scripts |
+| **SKL-006** | High | Instructions to change permissions, settings, or hooks |
+
+### Risk Scoring
+
+| Score Range | Risk Level | Recommendation |
+|-------------|------------|----------------|
+| **0** | Clean | No findings, safe to enable |
+| **1-3** | Low-Medium | Review findings, likely safe |
+| **4-6** | High | Needs attention before enabling |
+| **7-8** | Critical | Do not enable without remediation |
+| **9-10** | Severe | Multiple critical findings, likely malicious |
+
+## Output Format
+
+The skill generates detailed audit reports:
+
+```markdown
+# Skill Audit Report: my-skill
+
+**Path:** .claude/skills/my-skill/
+**Date:** 2026-01-30
+**Risk Score:** 3/10
+**Overall Severity:** Medium
+
+## Summary
+The skill uses WebFetch for external API calls but has no hooks or injection patterns.
+
+## Findings
+| # | ID | Severity | Finding | Location | Evidence |
+|---|---|---|---|---|---|
+| 1 | SKL-003 | Medium | WebFetch in allowed-tools | SKILL.md:4 | `allowed-tools: Read, WebFetch` |
+
+## Hardening Recommendations
+1. Remove WebFetch unless strictly required for the skill's purpose.
+```
+
+## Security Properties
+
+This skill is designed with security as the top priority:
+
+### Read-Only Analysis
+- Uses ONLY `Read`, `Grep`, `Glob` tools (plus `WebFetch` for remote GitHub audits)
+- Cannot modify files or execute commands
+- No system state changes
+
+### Anti-Injection Protection
+- All audited content treated as untrusted malicious input
+- Instructions found in audited files are flagged as findings
+- Never follows or executes instructions from audited content
+
+### Evidence Redaction
+- Secrets, tokens, and API keys found in evidence are automatically masked
+- Prevents accidental exposure of credentials in audit reports
+- Shows only first 4 and last 4 characters of sensitive values
+
+### Scoped WebFetch
+- WebFetch restricted to `raw.githubusercontent.com` and `api.github.com`
+- Only used for fetching remote skill files from GitHub
+- No redirects followed, no links from fetched content used
+- No arbitrary URL access
+
+### Isolated Execution
+- Runs in a forked subagent context (`context: fork`)
+- Prevents context contamination from audited content
+- Clean execution environment for each audit
+
+### Manual-Only Invocation
+- `disable-model-invocation: true` prevents auto-triggering
+- Must be invoked explicitly via `/skill-audit`
+- No automatic background scans
+
+### Remote Audit Limits
+- Maximum 20 files per remote audit
+- 100 KB file size limit
+- Large repositories require targeting a specific subdirectory
+
+## Use Cases
+
+### Pre-Installation Audit
+Audit skills from GitHub before installing them:
+```bash
+/skill-audit https://github.com/third-party/suspicious-skill
+```
+
+### Regular Security Reviews
+Audit all installed skills periodically:
+```bash
+/skill-audit
+```
+
+### Third-Party Skill Vetting
+Review community-contributed skills before enabling:
+```bash
+/skill-audit .claude/skills/community-skill
+```
+
+### Command Safety Check
+Verify custom commands don't have dangerous patterns:
+```bash
+/skill-audit .claude/commands/deploy.md
+```
+
+## How It Works
+
+```
+User Request
+    ↓
+skill-audit Skill
+    ↓
+Static Analysis Engine
+    ↓
+Security Report (Read-only, no modifications)
+```
+
+The skill performs purely static analysis without executing any code from the audited target. All analysis is based on pattern matching, AST analysis, and heuristic detection.
+
+## Key Features
+
+**Comprehensive Detection**
+- Hooks and auto-execution patterns
+- Prompt injection attempts
+- Excessive permissions
+- Credential access patterns
+- Privilege escalation attempts
+
+**Multi-Target Support**
+- Local skill directories
+- Individual command files
+- Remote GitHub repositories
+- Bulk project audits
+
+**Zero Side Effects**
+- Read-only operation
+- No file modifications
+- No command execution
+- Safe to run on any skill
+
+**Detailed Reporting**
+- Risk scoring (0-10 scale)
+- Severity classification
+- Specific evidence locations
+- Hardening recommendations
+
+## Structure
+
+```
+skill-audit/
+├── SKILL.md          # Skill definition + audit logic (single file)
+└── README.md         # This file
+```
+
+## Contributing
+
+Found a security pattern that should be detected? Submit an issue or pull request at:
+https://github.com/anysiteio/agent-skills/issues
+
+## Support
+
+- **GitHub Issues**: [github.com/anysiteio/agent-skills/issues](https://github.com/anysiteio/agent-skills/issues)
+- **Documentation**: [SKILL.md](SKILL.md)
+- **Anysite MCP**: [docs.anysite.io](https://docs.anysite.io)
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) file for details
+
+---
+
+**Note**: This is a security/defensive tool and operates independently from the anysite MCP server. It does not require anysite MCP server to function.