diff --git a/.gitignore b/.gitignore index 43d60da..b53d1a0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,10 @@ ``` -# Skills documentation -skills/**/*.md +# Compiled Python files +*.pyc +__pycache__/ + +# Environment files +.env +.env.local +*.env.* ``` \ No newline at end of file diff --git a/skills/example-skill/security-vulnerability-scanner/SKILL.md b/skills/example-skill/security-vulnerability-scanner/SKILL.md new file mode 100644 index 0000000..0d68819 --- /dev/null +++ b/skills/example-skill/security-vulnerability-scanner/SKILL.md @@ -0,0 +1,185 @@ +--- +name: "security-vulnerability-scanner" +description: "Analyzes codebases, dependency lists, or configuration files to identify security vulnerabilities, misconfigurations, and compliance gaps. Provides actionable remediation steps with severity ratings and references to CVEs or security standards." +version: "1.0.0" +tags: ["security", "vulnerability", "code-analysis", "compliance", "devsecops", "risk-assessment"] +context_priority: "high" +--- + +# Security Vulnerability Scanner + +## When to Use This Skill + +**Use this skill when:** +- You need to audit a codebase for common security vulnerabilities (OWASP Top 10, CWE) +- You want to scan dependency files (package.json, requirements.txt, pom.xml) for known CVEs +- You need to review infrastructure-as-code (Terraform, CloudFormation, Kubernetes) for misconfigurations +- You require a security assessment before deployment or release +- You need to generate compliance reports for security standards (SOC2, ISO 27001, PCI-DSS) + +**Do NOT use this skill when:** +- You need real-time threat detection or intrusion prevention +- You require penetration testing or active exploitation attempts +- The code is highly proprietary and cannot be shared with an LLM +- You need certified security audits for regulatory purposes + +## Core Workflow + +### Step 1: Input Analysis +Accept and parse the provided security scan target: +- Source code files or repositories +- Dependency manifest files +- Infrastructure-as-code templates +- Configuration files (Dockerfile, nginx.conf, etc.) +- API specifications or endpoint definitions + +Identify the technology stack, frameworks, and potential attack surface. + +### Step 2: Vulnerability Detection +Systematically analyze the input for security issues across multiple categories: + +**Code-Level Vulnerabilities:** +- Injection flaws (SQL, NoSQL, OS command, LDAP) +- Cross-site scripting (XSS) and CSRF +- Insecure deserialization +- Broken authentication and session management +- Sensitive data exposure +- Security misconfigurations +- Hardcoded credentials, API keys, or secrets + +**Dependency Vulnerabilities:** +- Outdated packages with known CVEs +- Deprecated or unmaintained libraries +- License compliance issues + +**Infrastructure Misconfigurations:** +- Overly permissive IAM policies +- Exposed ports or services +- Missing encryption at rest or in transit +- Insecure container configurations +- Publicly accessible storage buckets + +### Step 3: Severity Assessment +For each identified vulnerability: +1. Assign a severity rating (Critical, High, Medium, Low, Info) +2. Calculate CVSS score estimate where applicable +3. Determine exploitability and potential impact +4. Identify affected components and attack vectors +5. Reference relevant CVE IDs, CWE categories, or OWASP entries + +### Step 4: Remediation Guidance +Provide specific, actionable remediation steps: +- Code fixes with before/after examples +- Dependency version upgrades +- Configuration changes +- Architecture recommendations +- Links to official documentation and patches +- Estimated effort to fix (S/M/L) + +### Step 5: Report Generation +Compile findings into a structured security report with: +- Executive summary with risk overview +- Detailed vulnerability list sorted by severity +- Remediation roadmap with priorities +- Compliance gap analysis +- Recommended security controls and best practices + +## Output Format + +```json +{ + "scan_summary": { + "target": "string - description of scanned artifact", + "scan_date": "ISO 8601 timestamp", + "total_findings": "number", + "severity_breakdown": { + "critical": "number", + "high": "number", + "medium": "number", + "low": "number", + "info": "number" + }, + "risk_score": "number (0-100)" + }, + "vulnerabilities": [ + { + "id": "VULN-001", + "title": "string", + "category": "injection|auth|data_exposure|misconfiguration|dependency|other", + "severity": "critical|high|medium|low|info", + "cvss_estimate": "number (0.0-10.0)", + "cwe_id": "CWE-XXX (if applicable)", + "cve_ids": ["CVE-YYYY-XXXX"], + "location": { + "file": "string", + "line": "number or null", + "component": "string" + }, + "description": "detailed explanation of the vulnerability", + "evidence": "code snippet or configuration excerpt", + "impact": "potential consequences if exploited", + "remediation": { + "steps": ["step-by-step fix instructions"], + "code_fix": "before/after example if applicable", + "references": ["URLs to docs, patches, advisories"], + "estimated_effort": "S|M|L" + } + } + ], + "compliance_gaps": [ + { + "standard": "SOC2|ISO27001|PCI-DSS|GDPR|HIPAA", + "requirement": "specific control or requirement", + "status": "non-compliant|partial|compliant", + "findings": ["related vulnerability IDs"] + } + ], + "recommendations": [ + { + "priority": "immediate|short-term|long-term", + "category": "process|tooling|architecture|training", + "recommendation": "detailed suggestion", + "rationale": "why this matters" + } + ] +} +``` + +## Fallback Behavior + +**If input is incomplete or unclear:** +- Request clarification on what should be scanned +- Ask for specific files, code snippets, or dependency lists +- Offer to scan common file types if none are specified + +**If no vulnerabilities are found:** +- Confirm the analysis was thorough +- Provide security best practices for the technology stack +- Suggest additional scanning tools for comprehensive coverage +- Recommend periodic re-scanning as code evolves + +**If the scope is too large:** +- Propose focusing on high-risk areas first +- Suggest breaking the scan into logical components +- Prioritize critical paths (authentication, payment, data access) + +**If uncertain about a finding:** +- Clearly mark as "potential issue - manual verification recommended" +- Explain the uncertainty and what to check +- Provide guidance on how to validate + +## Examples + +### Example Input Types: +1. **Code Snippet:** A function handling user input and database queries +2. **Dependency File:** package.json, requirements.txt, Gemfile, pom.xml +3. **IaC Template:** Terraform .tf files, CloudFormation YAML, Kubernetes manifests +4. **Configuration:** Dockerfile, .env template, nginx.conf, security groups +5. **API Spec:** OpenAPI/Swagger definition with authentication flows + +### Example Findings: +- "SQL Injection in login function - unsanitized user input concatenated into query" +- "Hardcoded AWS secret key in source code at config/aws.js:15" +- "Outdated lodash@4.17.15 with prototype pollution vulnerability (CVE-2021-23337)" +- "S3 bucket configured with public read access - potential data exposure" +- "Container running as root user - privilege escalation risk" diff --git a/skills/example-skill/sql-query-optimizer/SKILL.md b/skills/example-skill/sql-query-optimizer/SKILL.md new file mode 100644 index 0000000..fbd2e24 --- /dev/null +++ b/skills/example-skill/sql-query-optimizer/SKILL.md @@ -0,0 +1,301 @@ +--- +name: "sql-query-optimizer" +description: "Analyzes SQL queries for performance bottlenecks, suggests optimizations including indexing strategies, query rewrites, and execution plan improvements. Supports multiple database engines (PostgreSQL, MySQL, SQL Server, Oracle) with engine-specific recommendations." +version: "1.0.0" +tags: ["sql", "database", "performance", "optimization", "query-tuning", "indexing"] +context_priority: "high" +--- + +# SQL Query Optimizer + +## When to Use This Skill + +**Use this skill when:** +- You have slow-running SQL queries that need performance improvement +- You want to optimize queries before deploying to production +- You need to understand query execution plans and identify bottlenecks +- You want recommendations for indexing strategies +- You need to refactor complex queries for better readability and performance +- You are troubleshooting database performance issues or high CPU/IO usage +- You want to learn SQL optimization best practices + +**Do NOT use this skill when:** +- You need to modify database schema or table structures directly +- You require actual execution statistics from a live database +- The query involves proprietary business logic that cannot be shared +- You need to perform capacity planning or hardware sizing + +## Core Workflow + +### Step 1: Query & Context Analysis +Parse and understand the input: +- The SQL query or query batch to optimize +- Database engine and version (PostgreSQL, MySQL, SQL Server, Oracle, etc.) +- Table schemas (columns, data types, existing indexes) +- Approximate table sizes (row counts) +- Current query performance metrics (execution time, rows examined, etc.) +- EXPLAIN/EXPLAIN ANALYZE output if available + +Identify: +- Query type (SELECT, INSERT, UPDATE, DELETE, MERGE) +- Join types and complexity +- Subqueries, CTEs, or derived tables +- Aggregations, grouping, and sorting operations +- Filter conditions and predicates + +### Step 2: Performance Bottleneck Detection +Analyze the query for common performance issues: + +**Index-Related Issues:** +- Missing indexes on filtered or joined columns +- Inefficient index usage (index scans instead of seeks) +- Redundant or overlapping indexes +- Covering index opportunities +- Index selectivity problems + +**Query Structure Issues:** +- N+1 query patterns +- Cartesian products from missing join conditions +- Non-SARGable predicates (functions on indexed columns) +- Implicit type conversions preventing index usage +- OR conditions that prevent index usage +- LIKE patterns with leading wildcards + +**Execution Plan Issues:** +- Full table scans on large tables +- Expensive sort or hash operations +- Temp table or file sort usage +- High cardinality estimates vs. actual rows +- Nested loop joins on large datasets + +**Resource Utilization:** +- Excessive memory grants +- High I/O operations +- CPU-intensive operations +- Lock contention potential + +### Step 3: Optimization Strategy Formulation +Develop specific optimization recommendations: + +**Index Recommendations:** +- Create new indexes with column order based on selectivity +- Suggest covering indexes to eliminate key lookups +- Recommend composite indexes for multi-column filters +- Identify indexes to drop or consolidate +- Provide CREATE INDEX statements + +**Query Rewrite Suggestions:** +- Convert subqueries to JOINs where beneficial +- Replace OR with UNION for better index usage +- Simplify complex CASE expressions +- Optimize EXISTS vs. IN vs. JOIN choices +- Restructure CTEs for materialization control +- Push predicates closer to base tables + +**Schema-Level Recommendations:** +- Partitioning strategies for large tables +- Denormalization opportunities +- Computed/persisted columns for expensive calculations +- Statistics update recommendations + +**Engine-Specific Optimizations:** +- PostgreSQL: BRIN indexes, partial indexes, parallel query hints +- MySQL: Index hints, optimizer_switch settings, partition pruning +- SQL Server: Query store hints, forced parameterization, columnstore indexes +- Oracle: Hints, SQL profiles, result caching + +### Step 4: Before/After Comparison +Provide: +- Original query with identified issues highlighted +- Optimized query with all changes applied +- Expected performance improvement estimate (% or x-factor) +- Trade-offs and considerations for each optimization +- Risks of the proposed changes + +### Step 5: Implementation Guidance +Deliver actionable next steps: +- Priority-ordered list of changes to implement +- Index creation scripts ready to execute +- Testing strategy (how to validate improvements) +- Monitoring recommendations (what metrics to track) +- Rollback plan if optimizations cause issues +- When to involve a DBA or database architect + +## Output Format + +```json +{ + "analysis_summary": { + "query_type": "SELECT|INSERT|UPDATE|DELETE|MERGE", + "database_engine": "PostgreSQL|MySQL|SQL Server|Oracle|Other", + "complexity_score": "low|medium|high", + "estimated_current_cost": "relative cost estimate", + "primary_bottlenecks": ["top 3-5 performance issues"], + "tables_involved": [ + { + "table_name": "string", + "estimated_rows": "number or 'unknown'", + "access_pattern": "full_scan|index_scan|seek", + "issues": ["specific issues with this table"] + } + ] + }, + "identified_issues": [ + { + "id": "ISSUE-001", + "category": "missing_index|non_sargable|full_scan|join_order|cardinality|other", + "severity": "critical|high|medium|low", + "location": "line number or clause description", + "description": "detailed explanation of the issue", + "impact": "performance consequence", + "evidence": "query snippet or execution plan detail" + } + ], + "optimizations": [ + { + "id": "OPT-001", + "type": "index_creation|query_rewrite|schema_change|configuration", + "priority": "immediate|high|medium|low", + "title": "short descriptive title", + "description": "what change to make", + "implementation": { + "sql_script": "CREATE INDEX or rewritten query", + "explanation": "why this works" + }, + "expected_improvement": "estimated % or x-factor speedup", + "trade_offs": ["write overhead, storage, maintenance"], + "risk_level": "low|medium|high", + "addresses_issues": ["ISSUE-001", "ISSUE-002"] + } + ], + "optimized_query": { + "full_query": "complete optimized SQL statement", + "changes_made": [ + { + "change": "description of modification", + "reason": "why it improves performance", + "line_reference": "original line or clause" + } + ], + "alternative_approaches": [ + { + "approach": "different optimization strategy", + "when_to_use": "scenarios where this is better", + "query_variant": "alternative SQL" + } + ] + }, + "index_recommendations": { + "create_indexes": [ + { + "table": "table_name", + "index_name": "idx_table_columns", + "columns": ["col1", "col2"], + "index_type": "btree|hash|covering|partial|columnstore", + "create_statement": "full CREATE INDEX statement", + "rationale": "why this index helps", + "estimated_size": "approximate size if known" + } + ], + "drop_indexes": [ + { + "index_name": "idx_to_drop", + "table": "table_name", + "reason": "why it should be removed" + } + ], + "modify_indexes": [ + { + "index_name": "idx_to_modify", + "recommended_change": "add/remove/reorder columns" + } + ] + }, + "testing_plan": { + "before_metrics": ["metrics to capture before change"], + "after_metrics": ["metrics to capture after change"], + "test_scenarios": ["test cases to run"], + "rollback_steps": ["how to revert if needed"] + }, + "additional_recommendations": [ + { + "category": "statistics|partitioning|caching|architecture", + "recommendation": "suggestion", + "priority": "immediate|short-term|long-term", + "effort": "S|M|L" + } + ] +} +``` + +## Fallback Behavior + +**If table schemas are not provided:** +- Make reasonable assumptions based on column names +- Note assumptions clearly in the analysis +- Provide general optimization principles that apply broadly +- Request schema information for more specific recommendations + +**If database engine is unknown:** +- Provide ANSI SQL optimizations that work across engines +- Note engine-specific features that could help if identified +- Ask user to specify their database system + +**If EXPLAIN output is not available:** +- Analyze the query structure statically +- Predict likely execution plan issues +- Recommend capturing EXPLAIN output for deeper analysis +- Provide heuristics-based optimization suggestions + +**If query is already well-optimized:** +- Confirm that the query follows best practices +- Suggest monitoring and baseline establishment +- Recommend indexing review if not recently done +- Propose application-level optimizations (caching, batching) + +**If the query is too complex for single-pass optimization:** +- Break down into logical components +- Optimize each component separately +- Suggest incremental optimization approach +- Recommend profiling individual operations + +## Examples + +### Example Input: +```sql +-- Database: PostgreSQL 14 +-- Table users: ~1M rows, Table orders: ~50M rows +SELECT u.name, u.email, COUNT(o.id) as order_count, SUM(o.total) as total_spent +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +WHERE YEAR(o.created_at) = 2023 +AND u.status = 'active' +GROUP BY u.id, u.name, u.email +HAVING SUM(o.total) > 1000 +ORDER BY total_spent DESC +LIMIT 100; +``` + +### Example Issues Identified: +1. **Non-SARGable predicate:** `YEAR(o.created_at) = 2023` prevents index usage +2. **Missing index:** No index on `orders(user_id, created_at, total)` +3. **Missing index:** No index on `users(status)` +4. **Inefficient aggregation:** Computing aggregates on large dataset before filtering + +### Example Optimized Query: +```sql +SELECT u.name, u.email, COUNT(o.id) as order_count, SUM(o.total) as total_spent +FROM users u +LEFT JOIN orders o ON u.id = o.user_id + AND o.created_at >= '2023-01-01' + AND o.created_at < '2024-01-01' +WHERE u.status = 'active' +GROUP BY u.id, u.name, u.email +HAVING SUM(o.total) > 1000 +ORDER BY total_spent DESC +LIMIT 100; + +-- Recommended indexes: +CREATE INDEX idx_orders_user_created_total ON orders(user_id, created_at, total); +CREATE INDEX idx_users_status ON users(status) WHERE status = 'active'; +``` diff --git a/skills/example-skill/user-story-generator/SKILL.md b/skills/example-skill/user-story-generator/SKILL.md new file mode 100644 index 0000000..2f3ed99 --- /dev/null +++ b/skills/example-skill/user-story-generator/SKILL.md @@ -0,0 +1,194 @@ +--- +name: "user-story-generator" +description: "Transforms product requirements, feature requests, bug reports, or high-level ideas into well-structured user stories with acceptance criteria, prioritization, and implementation guidance following Agile/Scrum best practices." +version: "1.0.0" +tags: ["agile", "user-stories", "product-management", "requirements", "scrum", "backlog"] +context_priority: "medium" +--- + +# User Story Generator + +## When to Use This Skill + +**Use this skill when:** +- You need to convert product requirements into actionable user stories for development teams +- You want to break down epic features into smaller, estimable story units +- You need to write clear acceptance criteria for testing and validation +- You are building or refining a product backlog +- You want to ensure user stories follow INVEST principles (Independent, Negotiable, Valuable, Estimable, Small, Testable) +- You need to generate story estimates or complexity scores + +**Do NOT use this skill when:** +- You need detailed technical specifications or architecture diagrams +- You require actual effort estimation from the development team +- The requirements are too vague to form coherent stories +- You need stakeholder approval or business case justification + +## Core Workflow + +### Step 1: Requirement Analysis +Parse and understand the input: +- Product requirements documents (PRDs) +- Feature requests from stakeholders or users +- Bug reports or improvement suggestions +- High-level epics or themes +- Customer feedback or support tickets +- Competitive analysis or market research + +Identify: +- Target users and personas +- Business value and objectives +- Functional and non-functional requirements +- Dependencies and constraints +- Success metrics and KPIs + +### Step 2: Story Decomposition +Break down requirements into individual user stories: +- Apply the standard format: "As a [type of user], I want [goal/desire] so that [benefit/value]" +- Ensure each story is small enough to complete in a single sprint +- Identify independent story units that can be developed separately +- Group related stories into logical themes or epics +- Flag dependencies between stories + +### Step 3: Acceptance Criteria Definition +For each user story, define clear acceptance criteria: +- Use Given/When/Then (Gherkin) format where applicable +- Cover happy path scenarios +- Include edge cases and error conditions +- Specify performance or quality requirements +- Define what "done" means for the story +- Ensure criteria are testable and unambiguous + +### Step 4: Prioritization & Estimation Support +Provide guidance on: +- **Priority Level:** Must-have, Should-have, Could-have, Won't-have (MoSCoW) +- **Business Value Score:** 1-10 rating based on impact +- **Complexity Indicator:** T-shirt sizing (XS, S, M, L, XL) or story point range +- **Risk Factors:** Technical uncertainty, dependencies, external factors +- **Sequencing:** Recommended order of implementation + +### Step 5: Story Enrichment +Add supporting details for development readiness: +- **Technical Notes:** Implementation hints, architectural considerations +- **UX/UI Requirements:** Wireframe references, design system components +- **Data Requirements:** Schema changes, migration needs, API contracts +- **Testing Strategy:** Unit tests, integration tests, E2E scenarios +- **Definition of Ready:** Prerequisites before development can start + +## Output Format + +```json +{ + "epic_summary": { + "title": "string - epic or feature name", + "description": "high-level overview of the feature", + "business_objective": "what problem this solves", + "target_users": ["list of user personas"], + "success_metrics": ["KPIs or success criteria"] + }, + "user_stories": [ + { + "id": "US-001", + "title": "short descriptive title", + "story": "As a [user type], I want [goal] so that [benefit]", + "priority": "must-have|should-have|could-have|wont-have", + "business_value": "number (1-10)", + "complexity": "XS|S|M|L|XL", + "estimated_points": "number or range (e.g., '3-5')", + "acceptance_criteria": [ + { + "scenario": "description of the scenario", + "given": "preconditions", + "when": "action taken", + "then": "expected outcome" + } + ], + "dependencies": ["IDs of dependent stories or external systems"], + "technical_notes": ["implementation hints or considerations"], + "ux_requirements": ["design or UX specifications"], + "data_requirements": ["database or data model changes"], + "testing_strategy": { + "unit_tests": ["key functions to test"], + "integration_tests": ["interfaces to validate"], + "e2e_scenarios": ["end-to-end flows to verify"] + }, + "definition_of_ready": [ + "prerequisites that must be met before development" + ], + "risks": ["potential blockers or uncertainties"] + } + ], + "implementation_roadmap": { + "recommended_sequence": ["ordered list of story IDs"], + "sprint_grouping": [ + { + "sprint": "Sprint 1", + "stories": ["US-001", "US-002"], + "theme": "foundation/setup", + "capacity_used": "estimated points" + } + ], + "critical_path": ["stories that block others"], + "quick_wins": ["low-effort, high-value stories"] + }, + "open_questions": [ + { + "question": "clarification needed", + "impact": "which stories are affected", + "recommended_action": "how to resolve" + } + ] +} +``` + +## Fallback Behavior + +**If requirements are vague or incomplete:** +- List specific information needed to write effective stories +- Propose assumptions and ask for validation +- Create placeholder stories marked as "needs refinement" +- Suggest stakeholder interviews or discovery sessions + +**If the scope is too large:** +- Recommend breaking the epic into multiple phases +- Identify MVP (Minimum Viable Product) stories +- Propose a phased rollout strategy +- Highlight which stories deliver core value vs. nice-to-haves + +**If user personas are unclear:** +- Suggest common personas for the domain +- Recommend user research or persona definition workshops +- Write stories with generic "user" and flag for refinement + +**If technical feasibility is uncertain:** +- Mark stories with "spike needed" flag +- Suggest time-boxed research stories +- Provide alternative implementation approaches to investigate + +## Examples + +### Example Input: +"We need a password reset feature for our web app. Users should be able to request a reset link via email, click the link, and set a new password. We also want to enforce password strength rules." + +### Example Output Stories: + +**US-001: Request Password Reset** +- *Story:* As a registered user who forgot their password, I want to request a password reset link via email so that I can regain access to my account. +- *Acceptance Criteria:* + - Given I am on the login page, when I click "Forgot Password", then I see an email input field + - Given I entered a valid email, when I submit the form, then I receive a confirmation message + - Given I entered an invalid email, when I submit the form, then I see a generic success message (security best practice) + +**US-002: Reset Password via Link** +- *Story:* As a user with a valid reset link, I want to set a new password so that I can access my account with updated credentials. +- *Acceptance Criteria:* + - Given I clicked a valid reset link, when I land on the reset page, then I see two password fields (new password + confirm) + - Given the reset link is expired (>24 hours), when I try to use it, then I see an error and option to request a new link + - Given I entered mismatched passwords, when I submit, then I see a validation error + +**US-003: Password Strength Validation** +- *Story:* As a security-conscious user, I want the system to enforce strong password rules so that my account is protected from brute-force attacks. +- *Acceptance Criteria:* + - Given I enter a weak password, when I submit, then I see specific feedback on what's missing + - Given my password meets all criteria (8+ chars, uppercase, lowercase, number, special char), when I submit, then the password is accepted + - Given I'm setting a new password, when it matches any of my last 5 passwords, then I'm required to choose a different one