# Skill Engine

> Shared frameworks, utilities, and design patterns used across multiple skills.

## Files

| File | Purpose | Used By |
|------|---------|---------|
| [kill-check-base.md](kill-check-base.md) | Shared GO/PIVOT/KILL evaluation framework | 0.4, 6.4, 7.6 Kill Checks |

## Skill Design Patterns

### Progressive Token Budgeting

> Adapted from athola/claude-night-market progressive loading pattern.

Skills should declare their estimated token cost in frontmatter:

```yaml
---
name: My Skill
estimated_tokens: 300  # tokens to load this skill
---
```

**Loading strategy:**
- **Hub loads first** (~150-400 tokens): Skill name, description, when-to-use
- **Modules on demand**: Full skill content loaded only when activated
- **Target**: 50-70% token savings by not loading unused skills

**Guidelines for token-efficient skills:**
| Skill Size | Token Budget | Use For |
|-----------|-------------|---------|
| Micro (<200 tokens) | Description + 3-5 rules | Simple disciplines, checklists |
| Standard (200-500 tokens) | Full process + examples | Most skills |
| Large (500-1000 tokens) | Multi-phase workflows + templates | Complex pipelines |
| Reference (1000+ tokens) | Move to `references/` subdirectory | Domain knowledge, schemas |

### Declarative Safety Rules

> Adapted from athola/claude-night-market hookify plugin pattern.

For rules that must ALWAYS be enforced (not just when a skill is active), use declarative rule files:

```yaml
# _engine/rules/no-secrets-in-code.md
---
rule: no-secrets-in-code
action: block  # block | warn | log
pattern: "(API_KEY|SECRET|PASSWORD|TOKEN)\\s*=\\s*['\"][^'\"]+['\"]"
enabled: true
severity: critical
---

# Rule description
Never commit hardcoded secrets. Use environment variables.
```

**Rule actions:**
| Action | Behavior |
|--------|----------|
| `block` | Prevent the action, require correction |
| `warn` | Allow but flag for review |
| `log` | Record for audit, don't interrupt |

**When to use rules vs. skills:**
| Use Rules | Use Skills |
|-----------|-----------|
| Must ALWAYS apply (security, style) | Activated for specific tasks |
| Binary (pass/fail) | Process-oriented (steps, workflow) |
| Stateless (check once) | Stateful (multi-step) |
| Fast to evaluate | May need context/research |

### Required Skill Sections

Every discipline skill SHOULD include:

1. **Frontmatter**: name, description, version, estimated_tokens
2. **When To Use / When NOT To Use**: Clear activation triggers
3. **Core Process**: The main workflow or protocol
4. **Rationalizations to Reject**: Agent loopholes and their counters
5. **Pre-Completion Checklist**: Gate before claiming done
6. **Integration with Other Skills**: Cross-references

## Vendor Skills Reference

For project-specific vendor skills, install based on your tech stack:

| Project Type | Install | Source |
|-------------|---------|--------|
| Supabase / Postgres | `npx skills add supabase/agent-skills` | [github.com/supabase/agent-skills](https://github.com/supabase/agent-skills) |
| React / Next.js | `npx skills add vercel-labs/agent-skills` | [github.com/vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
| Cloudflare (Workers, Pages) | Install from repo | [github.com/cloudflare/skills](https://github.com/cloudflare/skills) |
| Payments (Stripe) | `npx -y @stripe/mcp --tools=all` | [github.com/stripe/ai](https://github.com/stripe/ai) |
| Security (all projects) | Install from repo | [github.com/trailofbits/skills](https://github.com/trailofbits/skills) |
| Code Review / PRs | Install from repo | [github.com/getsentry/skills](https://github.com/getsentry/skills) |
| React Native / Expo | `npx skills add vercel-labs/agent-skills` | Includes React Native guidelines |
| Python projects | Install from repo | [github.com/trailofbits/skills](https://github.com/trailofbits/skills) (modern-python) |

### When to Install Vendor Skills

- **Always:** Trail of Bits security skills (all projects benefit from security review)
- **Per project:** Match your tech stack from the table above
- **Don't merge:** Keep vendor skills as separate installs, not merged into framework skills

### Curated Directory

For the full list of 200+ verified agent skills from official teams:
[github.com/VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)