📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+283
@@ -0,0 +1,283 @@
|
||||
# Preprocessing with `!command`
|
||||
|
||||
Deterministic context injection that runs before Claude sees the prompt.
|
||||
|
||||
## How It Works
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pr-summary
|
||||
---
|
||||
|
||||
## Current Branch
|
||||
!`git branch --show-current`
|
||||
|
||||
## Recent Commits
|
||||
!`git log --oneline -5`
|
||||
```
|
||||
|
||||
When skill loads:
|
||||
1. Shell commands inside `!` `` ` `` run first
|
||||
2. Output replaces the syntax
|
||||
3. Claude sees rendered output, not commands
|
||||
|
||||
**Claude receives:**
|
||||
```markdown
|
||||
## Current Branch
|
||||
feature/add-auth
|
||||
|
||||
## Recent Commits
|
||||
a1b2c3d Add JWT validation
|
||||
e4f5g6h Implement login endpoint
|
||||
...
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
```markdown
|
||||
# Inline
|
||||
Current branch: !`git branch --show-current`
|
||||
|
||||
# Block
|
||||
## Status
|
||||
!`git status`
|
||||
|
||||
# With formatting
|
||||
- **Diff**: !`gh pr diff`
|
||||
- **Comments**: !`gh pr view --comments`
|
||||
```
|
||||
|
||||
## When to Preprocess
|
||||
|
||||
| Use Case | Command | Why |
|
||||
|----------|---------|-----|
|
||||
| Git state | `!git status` | Snapshot at invocation |
|
||||
| PR context | `!gh pr diff` | Avoid tool call overhead |
|
||||
| Schema info | `!psql -c "\\d users"` | Fresh structure |
|
||||
| Environment | `!echo $NODE_ENV` | Runtime context |
|
||||
| File contents | `!cat config.json` | Static reference |
|
||||
| Versions | `!node --version` | Environment info |
|
||||
|
||||
## When NOT to Preprocess
|
||||
|
||||
| Avoid | Why | Alternative |
|
||||
|-------|-----|-------------|
|
||||
| Dynamic queries | Needs conversation context | Use Bash tool |
|
||||
| Large outputs | Bloats context | Summarize or Read tool |
|
||||
| Mutations | Side effects before thinking | Tool with confirmation |
|
||||
| Secrets | Ends up in context | Environment variables |
|
||||
| Interactive commands | Hangs | Avoid or timeout |
|
||||
|
||||
## Patterns
|
||||
|
||||
### Git Context
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: commit-review
|
||||
---
|
||||
|
||||
## Current State
|
||||
- **Branch**: !`git branch --show-current`
|
||||
- **Status**: !`git status --short`
|
||||
- **Staged**: !`git diff --cached --stat`
|
||||
|
||||
## Recent History
|
||||
!`git log --oneline -10`
|
||||
|
||||
Review changes and suggest commit message.
|
||||
```
|
||||
|
||||
### PR Workflow
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pr-summary
|
||||
context: fork
|
||||
agent: Explore
|
||||
allowed-tools: Bash(gh:*)
|
||||
---
|
||||
|
||||
## Pull Request
|
||||
|
||||
- **Title**: !`gh pr view --json title -q .title`
|
||||
- **Author**: !`gh pr view --json author -q .author.login`
|
||||
- **State**: !`gh pr view --json state -q .state`
|
||||
|
||||
## Changes
|
||||
!`gh pr diff --stat`
|
||||
|
||||
## Full Diff
|
||||
!`gh pr diff`
|
||||
|
||||
## Comments
|
||||
!`gh pr view --comments`
|
||||
|
||||
Summarize changes, highlight risks, note open discussions.
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: db-aware-query
|
||||
---
|
||||
|
||||
## Schema Reference
|
||||
|
||||
### Users Table
|
||||
!`psql -c "\\d users" --no-psqlrc`
|
||||
|
||||
### Orders Table
|
||||
!`psql -c "\\d orders" --no-psqlrc`
|
||||
|
||||
Write queries aware of this schema.
|
||||
```
|
||||
|
||||
### Environment Info
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: debug-env
|
||||
---
|
||||
|
||||
## Runtime Environment
|
||||
|
||||
| Component | Version |
|
||||
|-----------|---------|
|
||||
| Node | !`node --version` |
|
||||
| npm | !`npm --version` |
|
||||
| TypeScript | !`npx tsc --version` |
|
||||
|
||||
## Config
|
||||
!`cat package.json | jq '{name, version, scripts}'`
|
||||
```
|
||||
|
||||
### Incident Context
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: incident-triage
|
||||
---
|
||||
|
||||
## Current Time
|
||||
!`date -u +"%Y-%m-%dT%H:%M:%SZ"`
|
||||
|
||||
## Recent Errors
|
||||
!`tail -50 /var/log/app.log | grep ERROR`
|
||||
|
||||
## System State
|
||||
!`ps aux | head -10`
|
||||
!`df -h | head -5`
|
||||
|
||||
Assess severity and identify immediate actions.
|
||||
```
|
||||
|
||||
## Combining with Artifacts
|
||||
|
||||
Preprocessing captures **live state**; artifacts capture **work state**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deploy-preflight
|
||||
---
|
||||
|
||||
## Live State (preprocessed)
|
||||
- **Branch**: !`git branch --show-current`
|
||||
- **Clean**: !`git status --porcelain`
|
||||
- **Tests**: !`npm test 2>&1 | tail -5`
|
||||
|
||||
## Work State (from artifacts)
|
||||
Read artifacts/plan.md for deployment checklist.
|
||||
Read artifacts/review-notes.md for outstanding issues.
|
||||
|
||||
Proceed only if live state is clean AND artifacts show ready.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Commands that fail show error output:
|
||||
|
||||
```markdown
|
||||
# If git not installed:
|
||||
## Current Branch
|
||||
!`git branch --show-current`
|
||||
|
||||
# Claude sees:
|
||||
## Current Branch
|
||||
bash: git: command not found
|
||||
```
|
||||
|
||||
Handle gracefully in skill:
|
||||
|
||||
```markdown
|
||||
## Prerequisites
|
||||
|
||||
If any preprocessing shows errors (command not found, permission denied),
|
||||
report the issue and do not proceed.
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Never preprocess:**
|
||||
- Commands that output secrets (`cat ~/.ssh/id_rsa`)
|
||||
- API calls with credentials in output
|
||||
- Anything that exposes tokens/passwords
|
||||
|
||||
**Safe patterns:**
|
||||
- Git operations (on repo content, not remotes with embedded creds)
|
||||
- System info (versions, paths)
|
||||
- File structure (ls, find)
|
||||
- Log snippets (ensure logs don't contain secrets)
|
||||
|
||||
## Performance
|
||||
|
||||
Preprocessing runs synchronously before skill loads. Keep commands fast:
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `git status` | `git clone ...` |
|
||||
| `head -100 file` | `cat giant-file` |
|
||||
| `ls -la` | `find / -name ...` |
|
||||
| `jq .field file.json` | `curl slow-api` |
|
||||
|
||||
If command might be slow, use tools instead (can stream output, user sees progress).
|
||||
|
||||
## Timeouts
|
||||
|
||||
Preprocessing commands have a **5-second timeout**. Commands exceeding this will:
|
||||
- Be terminated
|
||||
- Show timeout error in output
|
||||
- Still allow skill to load (with error visible)
|
||||
|
||||
**Implications:**
|
||||
- Keep commands under 2 seconds for reliable execution
|
||||
- Network calls are risky (latency varies)
|
||||
- Large file operations may timeout
|
||||
- Complex pipelines may need optimization
|
||||
|
||||
**Workarounds for slow operations:**
|
||||
|
||||
| Slow Pattern | Alternative |
|
||||
|--------------|-------------|
|
||||
| `curl api/endpoint` | Use WebFetch tool instead |
|
||||
| `find / -name ...` | Narrow scope or use Glob tool |
|
||||
| `git log --all` | Limit with `-n 10` |
|
||||
| `npm test` | Run as tool (shows progress) |
|
||||
|
||||
**No timeout control**: You cannot extend the timeout. If a command needs more than 5 seconds, it belongs in a tool call, not preprocessing.
|
||||
|
||||
## Debugging
|
||||
|
||||
If preprocessing seems wrong:
|
||||
|
||||
1. Run commands manually in terminal
|
||||
2. Check shell environment (preprocessing uses default shell)
|
||||
3. Verify paths are absolute or relative to skill location
|
||||
4. Check for quoting issues in complex commands
|
||||
|
||||
```markdown
|
||||
# Debug with echo
|
||||
!`echo "PWD: $(pwd)"`
|
||||
!`echo "PATH: $PATH"`
|
||||
```
|
||||
Reference in New Issue
Block a user