@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/.agent/skills/problem-solving/simplification-cascades/SKILL.md

@@ -1,76 +0,0 @@
----
-name: Simplification Cascades
-description: Find one insight that eliminates multiple components - "if this is true, we don't need X, Y, or Z"
-when_to_use: when implementing the same concept multiple ways, accumulating special cases, or complexity is spiraling
-version: 1.1.0
----
-
-# Simplification Cascades
-
-## Overview
-
-Sometimes one insight eliminates 10 things. Look for the unifying principle that makes multiple components unnecessary.
-
-**Core principle:** "Everything is a special case of..." collapses complexity dramatically.
-
-## Quick Reference
-
-| Symptom | Likely Cascade |
-|---------|----------------|
-| Same thing implemented 5+ ways | Abstract the common pattern |
-| Growing special case list | Find the general case |
-| Complex rules with exceptions | Find the rule that has no exceptions |
-| Excessive config options | Find defaults that work for 95% |
-
-## The Pattern
-
-**Look for:**
-- Multiple implementations of similar concepts
-- Special case handling everywhere
-- "We need to handle A, B, C, D differently..."
-- Complex rules with many exceptions
-
-**Ask:** "What if they're all the same thing underneath?"
-
-## Examples
-
-### Cascade 1: Stream Abstraction
-**Before:** Separate handlers for batch/real-time/file/network data
-**Insight:** "All inputs are streams - just different sources"
-**After:** One stream processor, multiple stream sources
-**Eliminated:** 4 separate implementations
-
-### Cascade 2: Resource Governance
-**Before:** Session tracking, rate limiting, file validation, connection pooling (all separate)
-**Insight:** "All are per-entity resource limits"
-**After:** One ResourceGovernor with 4 resource types
-**Eliminated:** 4 custom enforcement systems
-
-### Cascade 3: Immutability
-**Before:** Defensive copying, locking, cache invalidation, temporal coupling
-**Insight:** "Treat everything as immutable data + transformations"
-**After:** Functional programming patterns
-**Eliminated:** Entire classes of synchronization problems
-
-## Process
-
-1. **List the variations** - What's implemented multiple ways?
-2. **Find the essence** - What's the same underneath?
-3. **Extract abstraction** - What's the domain-independent pattern?
-4. **Test it** - Do all cases fit cleanly?
-5. **Measure cascade** - How many things become unnecessary?
-
-## Red Flags You're Missing a Cascade
-
-- "We just need to add one more case..." (repeating forever)
-- "These are all similar but different" (maybe they're the same?)
-- Refactoring feels like whack-a-mole (fix one, break another)
-- Growing configuration file
-- "Don't touch that, it's complicated" (complexity hiding pattern)
-
-## Remember
-
-- Simplification cascades = 10x wins, not 10% improvements
-- One powerful abstraction > ten clever hacks
-- The pattern is usually already there, just needs recognition
-- Measure in "how many things can we delete?"

package/.agent/skills/problem-solving/when-stuck/SKILL.md

@@ -1,88 +0,0 @@
----
-name: When Stuck - Problem-Solving Dispatch
-description: Dispatch to the right problem-solving technique based on how you're stuck
-when_to_use: when stuck and unsure which problem-solving technique to apply for your specific type of stuck-ness
-version: 1.1.0
----
-
-# When Stuck - Problem-Solving Dispatch
-
-## Overview
-
-Different stuck-types need different techniques. This skill helps you quickly identify which problem-solving skill to use.
-
-**Core principle:** Match stuck-symptom to technique.
-
-## Quick Dispatch
-
-```dot
-digraph stuck_dispatch {
-    rankdir=TB;
-    node [shape=box, style=rounded];
-
-    stuck [label="You're Stuck", shape=ellipse, style=filled, fillcolor=lightblue];
-
-    complexity [label="Same thing implemented 5+ ways?\nGrowing special cases?\nExcessive if/else?"];
-    innovation [label="Can't find fitting approach?\nConventional solutions inadequate?\nNeed breakthrough?"];
-    patterns [label="Same issue in different places?\nFeels familiar across domains?\nReinventing wheels?"];
-    assumptions [label="Solution feels forced?\n'This must be done this way'?\nStuck on assumptions?"];
-    scale [label="Will this work at production?\nEdge cases unclear?\nUnsure of limits?"];
-    bugs [label="Code behaving wrong?\nTest failing?\nUnexpected output?"];
-
-    stuck -> complexity;
-    stuck -> innovation;
-    stuck -> patterns;
-    stuck -> assumptions;
-    stuck -> scale;
-    stuck -> bugs;
-
-    complexity -> simp [label="yes"];
-    innovation -> collision [label="yes"];
-    patterns -> meta [label="yes"];
-    assumptions -> invert [label="yes"];
-    scale -> scale_skill [label="yes"];
-    bugs -> debug [label="yes"];
-
-    simp [label="skills/problem-solving/\nsimplification-cascades", shape=box, style="rounded,filled", fillcolor=lightgreen];
-    collision [label="skills/problem-solving/\ncollision-zone-thinking", shape=box, style="rounded,filled", fillcolor=lightgreen];
-    meta [label="skills/problem-solving/\nmeta-pattern-recognition", shape=box, style="rounded,filled", fillcolor=lightgreen];
-    invert [label="skills/problem-solving/\ninversion-exercise", shape=box, style="rounded,filled", fillcolor=lightgreen];
-    scale_skill [label="skills/problem-solving/\nscale-game", shape=box, style="rounded,filled", fillcolor=lightgreen];
-    debug [label="skills/debugging/\nsystematic-debugging", shape=box, style="rounded,filled", fillcolor=lightyellow];
-}
-```
-
-## Stuck-Type → Technique
-
-| How You're Stuck | Use This Skill |
-|------------------|----------------|
-| **Complexity spiraling** - Same thing 5+ ways, growing special cases | skills/problem-solving/simplification-cascades |
-| **Need innovation** - Conventional solutions inadequate, can't find fitting approach | skills/problem-solving/collision-zone-thinking |
-| **Recurring patterns** - Same issue different places, reinventing wheels | skills/problem-solving/meta-pattern-recognition |
-| **Forced by assumptions** - "Must be done this way", can't question premise | skills/problem-solving/inversion-exercise |
-| **Scale uncertainty** - Will it work in production? Edge cases unclear? | skills/problem-solving/scale-game |
-| **Code broken** - Wrong behavior, test failing, unexpected output | skills/debugging/systematic-debugging |
-| **Multiple independent problems** - Can parallelize investigation | skills/collaboration/dispatching-parallel-agents |
-| **Root cause unknown** - Symptom clear, cause hidden | skills/debugging/root-cause-tracing |
-
-## Process
-
-1. **Identify stuck-type** - What symptom matches above?
-2. **Load that skill** - Read the specific technique
-3. **Apply technique** - Follow its process
-4. **If still stuck** - Try different technique or combine
-
-## Combining Techniques
-
-Some problems need multiple techniques:
-
-- **Simplification + Meta-pattern**: Find pattern, then simplify all instances
-- **Collision + Inversion**: Force metaphor, then invert its assumptions
-- **Scale + Simplification**: Extremes reveal what to eliminate
-
-## Remember
-
-- Match symptom to technique
-- One technique at a time
-- Combine if first doesn't work
-- Document what you tried

package/.agent/skills/python-patterns/SKILL.md

@@ -1,80 +0,0 @@
----
-name: python-patterns
-description: Python development principles and decision-making. Framework selection (FastAPI/Django/Flask), async patterns, type hints, project structure. Use when building Python APIs, backend services, or scripts. Teaches thinking, not copying.
----
-
-# Python Patterns
-
-> Python development principles and decision-making for 2025.
-> **Learn to THINK, not memorize patterns.**
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for framework preference when unclear
-- Choose async vs sync based on CONTEXT
-- Don't default to same framework every time
-
-## Quick References
-
-| Topic | Reference |
-|-------|-----------|
-| Framework Selection | [framework-selection.md](./references/framework-selection.md) |
-| Async Patterns | [async-patterns.md](./references/async-patterns.md) |
-| Type Hints | [type-hints.md](./references/type-hints.md) |
-| Project Structure | [project-structure.md](./references/project-structure.md) |
-| FastAPI Best Practices | [fastapi-patterns.md](./references/fastapi-patterns.md) |
-| Django Best Practices | [django-patterns.md](./references/django-patterns.md) |
-| Testing Strategy | [testing-patterns.md](./references/testing-patterns.md) |
-
-## Framework Decision Tree
-
-```
-What are you building?
-│
-├── API-first / Microservices → FastAPI
-├── Full-stack web / CMS / Admin → Django
-├── Simple / Script / Learning → Flask
-├── AI/ML API serving → FastAPI
-└── Background workers → Celery + any
-```
-
-## Async vs Sync Decision
-
-```
-I/O-bound → async (waiting for external)
-CPU-bound → sync + multiprocessing (computing)
-
-Don't:
-├── Mix sync and async carelessly
-├── Use sync libraries in async code
-└── Force async for CPU work
-```
-
-## Decision Checklist
-
-Before implementing:
-
-- [ ] Asked user about framework preference?
-- [ ] Chosen framework for THIS context?
-- [ ] Decided async vs sync?
-- [ ] Planned type hint strategy?
-- [ ] Defined project structure?
-- [ ] Considered background tasks?
-
-## Anti-Patterns
-
-### ❌ DON'T:
-- Default to Django for simple APIs
-- Use sync libraries in async code
-- Skip type hints for public APIs
-- Put business logic in routes/views
-
-### ✅ DO:
-- Choose framework based on context
-- Ask about async requirements
-- Use Pydantic for validation
-- Separate concerns (routes → services → repos)
-
-> **Remember**: Python patterns are about decision-making for YOUR specific context.

package/.agent/skills/python-patterns/references/async-patterns.md

@@ -1,57 +0,0 @@
-# Async Patterns
-
-## When to Use Async
-
-```
-async def is better when:
-├── I/O-bound operations (database, HTTP, file)
-├── Many concurrent connections
-├── Real-time features
-├── Microservices communication
-└── FastAPI/Starlette/Django ASGI
-
-def (sync) is better when:
-├── CPU-bound operations
-├── Simple scripts
-├── Legacy codebase
-├── Team unfamiliar with async
-└── Blocking libraries (no async version)
-```
-
-## The Golden Rule
-
-```
-I/O-bound → async (waiting for external)
-CPU-bound → sync + multiprocessing (computing)
-
-Don't:
-├── Mix sync and async carelessly
-├── Use sync libraries in async code
-└── Force async for CPU work
-```
-
-## Async Library Selection
-
-| Need | Async Library |
-|------|---------------|
-| HTTP client | httpx |
-| PostgreSQL | asyncpg |
-| Redis | aioredis / redis-py async |
-| File I/O | aiofiles |
-| Database ORM | SQLAlchemy 2.0 async, Tortoise |
-
-## FastAPI async def vs def
-
-```
-Use async def when:
-├── Using async database drivers
-├── Making async HTTP calls
-├── I/O-bound operations
-└── Want to handle concurrency
-
-Use def when:
-├── Blocking operations
-├── Sync database drivers
-├── CPU-bound work
-└── FastAPI runs in threadpool automatically
-```

package/.agent/skills/python-patterns/references/django-patterns.md

@@ -1,41 +0,0 @@
-# Django Best Practices (2025)
-
-## Django Async (Django 5.0+)
-
-```
-Django supports async:
-├── Async views
-├── Async middleware
-├── Async ORM (limited)
-└── ASGI deployment
-
-When to use async in Django:
-├── External API calls
-├── WebSocket (Channels)
-├── High-concurrency views
-└── Background task triggering
-```
-
-## Model Design
-
-```
-Model design:
-├── Fat models, thin views
-├── Use managers for common queries
-├── Abstract base classes for shared fields
-
-Views:
-├── Class-based for complex CRUD
-├── Function-based for simple endpoints
-├── Use viewsets with DRF
-```
-
-## Query Optimization
-
-```
-Queries:
-├── select_related() for FKs
-├── prefetch_related() for M2M
-├── Avoid N+1 queries
-└── Use .only() for specific fields
-```

package/.agent/skills/python-patterns/references/fastapi-patterns.md

@@ -1,54 +0,0 @@
-# FastAPI Best Practices
-
-## Dependency Injection
-
-```
-Use dependencies for:
-├── Database sessions
-├── Current user / Auth
-├── Configuration
-├── Shared resources
-
-Benefits:
-├── Testability (mock dependencies)
-├── Clean separation
-├── Automatic cleanup (yield)
-```
-
-## Pydantic v2 Integration
-
-```python
-# Request validation
-@app.post("/users")
-async def create(user: UserCreate) -> UserResponse:
-    # user is already validated
-    ...
-
-# Response serialization
-# Return type becomes response schema
-```
-
-## Error Handling
-
-```
-In FastAPI:
-├── Create custom exception classes
-├── Register exception handlers
-├── Return consistent error format
-└── Log without exposing internals
-
-Pattern:
-├── Raise domain exceptions in services
-├── Catch and transform in handlers
-└── Client gets clean error response
-```
-
-## Error Response Format
-
-```
-Include:
-├── Error code (programmatic)
-├── Message (human readable)
-├── Details (field-level when applicable)
-└── NOT stack traces (security)
-```

package/.agent/skills/python-patterns/references/framework-selection.md

@@ -1,39 +0,0 @@
-# Framework Selection (2025)
-
-## Decision Tree
-
-```
-What are you building?
-│
-├── API-first / Microservices
-│   └── FastAPI (async, modern, fast)
-│
-├── Full-stack web / CMS / Admin
-│   └── Django (batteries-included)
-│
-├── Simple / Script / Learning
-│   └── Flask (minimal, flexible)
-│
-├── AI/ML API serving
-│   └── FastAPI (Pydantic, async, uvicorn)
-│
-└── Background workers
-    └── Celery + any framework
-```
-
-## Comparison
-
-| Factor | FastAPI | Django | Flask |
-|--------|---------|--------|-------|
-| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
-| **Async** | Native | Django 5.0+ | Via extensions |
-| **Admin** | Manual | Built-in | Via extensions |
-| **ORM** | Choose your own | Django ORM | Choose your own |
-| **Learning curve** | Low | Medium | Low |
-
-## Selection Questions
-
-1. Is this API-only or full-stack?
-2. Need admin interface?
-3. Team familiar with async?
-4. Existing infrastructure?

package/.agent/skills/python-patterns/references/project-structure.md

@@ -1,80 +0,0 @@
-# Project Structure Principles
-
-## Structure by Size
-
-```
-Small project / Script:
-├── main.py
-├── utils.py
-└── requirements.txt
-
-Medium API:
-├── app/
-│   ├── __init__.py
-│   ├── main.py
-│   ├── models/
-│   ├── routes/
-│   ├── services/
-│   └── schemas/
-├── tests/
-└── pyproject.toml
-
-Large application:
-├── src/
-│   └── myapp/
-│       ├── core/
-│       ├── api/
-│       ├── services/
-│       ├── models/
-│       └── ...
-├── tests/
-└── pyproject.toml
-```
-
-## FastAPI Structure
-
-```
-Organize by feature or layer:
-
-By layer:
-├── routes/ (API endpoints)
-├── services/ (business logic)
-├── models/ (database models)
-├── schemas/ (Pydantic models)
-└── dependencies/ (shared deps)
-
-By feature:
-├── users/
-│   ├── routes.py
-│   ├── service.py
-│   └── schemas.py
-└── products/
-    └── ...
-```
-
-## Background Tasks Selection
-
-| Solution | Best For |
-|----------|----------|
-| **BackgroundTasks** | Simple, in-process tasks |
-| **Celery** | Distributed, complex workflows |
-| **ARQ** | Async, Redis-based |
-| **RQ** | Simple Redis queue |
-| **Dramatiq** | Actor-based, simpler than Celery |
-
-## When to Use Each
-
-```
-FastAPI BackgroundTasks:
-├── Quick operations
-├── No persistence needed
-├── Fire-and-forget
-└── Same process
-
-Celery/ARQ:
-├── Long-running tasks
-├── Need retry logic
-├── Distributed workers
-├── Persistent queue
-└── Complex workflows
-```

package/.agent/skills/python-patterns/references/testing-patterns.md

@@ -1,34 +0,0 @@
-# Testing Patterns
-
-## Testing Strategy
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | pytest |
-| **Integration** | API endpoints | pytest + httpx/TestClient |
-| **E2E** | Full workflows | pytest + DB |
-
-## Async Testing
-
-```python
-# Use pytest-asyncio for async tests
-
-import pytest
-from httpx import AsyncClient
-
-@pytest.mark.asyncio
-async def test_endpoint():
-    async with AsyncClient(app=app, base_url="http://test") as client:
-        response = await client.get("/users")
-        assert response.status_code == 200
-```
-
-## Common Fixtures
-
-```
-Common fixtures:
-├── db_session → Database connection
-├── client → Test client
-├── authenticated_user → User with token
-└── sample_data → Test data setup
-```

package/.agent/skills/python-patterns/references/type-hints.md

@@ -1,51 +0,0 @@
-# Type Hints Strategy
-
-## When to Type
-
-```
-Always type:
-├── Function parameters
-├── Return types
-├── Class attributes
-├── Public APIs
-
-Can skip:
-├── Local variables (let inference work)
-├── One-off scripts
-├── Tests (usually)
-```
-
-## Common Type Patterns
-
-```python
-# Optional → might be None
-from typing import Optional
-def find_user(id: int) -> Optional[User]: ...
-
-# Union → one of multiple types
-def process(data: str | dict) -> None: ...
-
-# Generic collections
-def get_items() -> list[Item]: ...
-def get_mapping() -> dict[str, int]: ...
-
-# Callable
-from typing import Callable
-def apply(fn: Callable[[int], str]) -> str: ...
-```
-
-## Pydantic for Validation
-
-```
-When to use Pydantic:
-├── API request/response models
-├── Configuration/settings
-├── Data validation
-├── Serialization
-
-Benefits:
-├── Runtime validation
-├── Auto-generated JSON schema
-├── Works with FastAPI natively
-└── Clear error messages
-```