@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills-cursor/create-skill/references/authoring-guide.md

@@ -0,0 +1,182 @@
+# Skill Authoring Guide (reference)
+
+Extended patterns, workflows, and checklists for `create-skill`. Read when drafting
+non-trivial skills.
+
+---
+
+## Common Patterns
+
+### Template Pattern
+
+Provide output format templates:
+
+```markdown
+## Report structure
+
+Use this template:
+
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+```
+
+### Examples Pattern
+
+For skills where output quality depends on seeing examples:
+
+```markdown
+## Commit message format
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+```
+
+### Workflow Pattern
+
+Use numbered steps with a checklist only where order is load-bearing (migrations, auth flows, destructive ops, baseline capture). For judgment work, state the outcome, the constraints, and how to verify - the agent's own plan beats a hand-written script:
+
+```markdown
+Task Progress:
+- [ ] Step 1: Analyze the form
+- [ ] Step 2: Create field mapping
+- [ ] Step 3: Validate mapping
+```
+
+### Conditional Workflow Pattern
+
+Guide through decision points — creation vs editing branches.
+
+### Feedback Loop Pattern
+
+For quality-critical tasks: edit → validate script → fix → re-validate before proceeding.
+
+---
+
+## Utility Scripts
+
+Pre-made scripts offer advantages over generated code:
+- More reliable than generated code
+- Save tokens (no code in context)
+- Ensure consistency across uses
+
+Make clear whether the agent should **execute** the script (most common) or **read** it as reference.
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Windows-Style Paths
+- ✅ Use: `scripts/helper.py`
+- ❌ Avoid: `scripts\helper.py`
+
+### 2. Too Many Options
+Provide a default with one escape hatch, not a menu of equals.
+
+### 3. Time-Sensitive Information
+Use "Current method" + collapsible "Old patterns (deprecated)" instead of dates in prose.
+
+### 4. Inconsistent Terminology
+Choose one term and use it throughout (e.g. always "API endpoint").
+
+### 5. Vague Skill Names
+- ✅ Good: `processing-pdfs`, `analyzing-spreadsheets`
+- ❌ Avoid: `helper`, `utils`, `tools`
+
+---
+
+## Skill Creation Workflow
+
+### Phase 1: Discovery
+
+Gather: purpose, storage location, trigger scenarios, constraints, existing patterns.
+
+### Phase 2: Design
+
+1. Draft skill name (lowercase, hyphens, max 64 chars)
+2. Write specific third-person description
+3. Outline main sections
+4. Identify supporting files or scripts
+
+### Phase 3: Implementation
+
+1. Create directory structure
+2. Write SKILL.md with frontmatter (`name`, `description`; when the skill also ships to Claude Code, add `effort: high` for audit / plan / security / judge work and `effort: low` for mechanical fixed-sequence work - the model default is medium, Claude Code honors the key, Cursor ignores it)
+3. Create reference files
+4. Create utility scripts if needed
+
+### Phase 4: Verification
+
+1. SKILL.md under 500 lines
+2. Description specific with trigger terms
+3. Consistent terminology
+4. File references one level deep
+5. Test discovery and application
+
+---
+
+## Complete Example
+
+**Directory structure:**
+
+```
+code-review/
+├── SKILL.md
+├── STANDARDS.md
+└── examples.md
+```
+
+**SKILL.md skeleton:**
+
+```markdown
+---
+name: code-review
+description: Review code for quality, security, and maintainability. Use when reviewing PRs or when the user asks for a code review.
+---
+
+# Code Review
+
+## What a review covers
+Correctness and edge cases, security, readability, and whether the tests
+prove the change. Report each finding as file:line, the defect, and the
+input that triggers it.
+
+## Additional Resources
+- [STANDARDS.md](STANDARDS.md)
+- [examples.md](examples.md)
+```
+
+---
+
+## Summary Checklist
+
+### Core Quality
+- [ ] Description is specific and includes key terms
+- [ ] Description includes both WHAT and WHEN
+- [ ] Written in third person
+- [ ] SKILL.md body is under 500 lines
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+
+### Structure
+- [ ] File references are one level deep
+- [ ] Progressive disclosure used appropriately
+- [ ] Numbered steps only where order is load-bearing; outcomes and constraints elsewhere
+- [ ] No time-sensitive information
+
+### If Including Scripts
+- [ ] Scripts solve problems rather than punt
+- [ ] Required packages are documented
+- [ ] Error handling is explicit and helpful
+- [ ] No Windows-style paths

package/skills-cursor/create-subagent/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: create-subagent
+description: Create custom subagents for specialized AI tasks. Use when the user wants to create a new type of subagent, set up task-specific agents, configure code reviewers, debuggers, or domain-specific assistants with custom prompts.
+disable-model-invocation: true
+---
+# Creating Custom Subagents
+
+This skill guides you through creating custom subagents for Cursor. Subagents are specialized AI assistants that run in isolated contexts with custom system prompts.
+
+## When to Use Subagents
+
+Subagents help you:
+- **Preserve context** by isolating exploration from your main conversation
+- **Specialize behavior** with focused system prompts for specific domains
+- **Reuse configurations** across projects with user-level subagents
+
+Delegate when the track is sizeable and independent, or when its output is verbose and the main context does not need it; launch independent subagents in one message. A handful of tool calls is cheaper inline. Brief each subagent precisely once and commit to the delegation.
+
+### Inferring from Context
+
+If you have previous conversation context, infer the subagent's purpose and behavior from what was discussed. Create the subagent based on specialized tasks or workflows that emerged in the conversation.
+
+## Subagent Locations
+
+| Location | Scope | Priority |
+|----------|-------|----------|
+| `.cursor/agents/` | Current project | Higher |
+| `~/.cursor/agents/` | All your projects | Lower |
+
+When multiple subagents share the same name, the higher-priority location wins.
+
+**Project subagents** (`.cursor/agents/`): Ideal for codebase-specific agents. Check into version control to share with your team.
+
+**User subagents** (`~/.cursor/agents/`): Personal agents available across all your projects.
+
+## Subagent File Format
+
+Create a `.md` file with YAML frontmatter and a markdown body (the system prompt):
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for quality and best practices
+---
+
+You are a code reviewer. When invoked, analyze the code and provide
+specific, actionable feedback on quality, security, and best practices.
+```
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (lowercase letters and hyphens only) |
+| `description` | When to delegate to this subagent (be specific!) |
+
+### Optional fields (Claude Code)
+
+Claude Code reads the same format from `.claude/agents/` and `~/.claude/agents/` and honors these; Cursor ignores keys it does not know.
+
+| Field | Use |
+|-------|-----|
+| `effort` | `low` / `medium` / `high` / `xhigh` / `max`. Opus 5.5 defaults to `medium`; set `high` for reviewer, judge, security, and architecture agents, `low` for read-only inventory or handoff agents. Prose like "think carefully" does nothing — this is the control. |
+| `model` | Pin a model alias (`opus`, `sonnet`, `haiku`); omit to inherit. |
+| `tools` | Restrict the tool set (read-only reviewers get no edit tools). |
+| `maxTurns` | Cap turns for bounded jobs. |
+| `memory`, `isolation`, `omitClaudeMd` | Persistent memory, worktree isolation, skip loading CLAUDE.md. |
+
+## Writing Effective Descriptions
+
+The description is **critical** - the AI uses it to decide when to delegate.
+
+```yaml
+# ❌ Too vague
+description: Helps with code
+
+# ✅ Specific and actionable
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+```
+
+Say when delegating pays — a sizeable, independent track, or verbose output the main context does not need. Add "use proactively" only when the agent visibly under-delegates; current models delegate readily, and a blanket booster pulls small tasks into subagents.
+
+## Example Subagents
+
+### Code Reviewer
+
+```markdown
+---
+name: code-reviewer
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review for correctness and requirement gaps: logic errors, unhandled failure paths, exposed secrets or keys, missing input validation, and behavior the task asked for that is absent. Mention style only where it hides a bug. Tie each finding to a file and line and say what input or state makes it fail.
+
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.
+```
+
+### Debugger
+
+```markdown
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
+---
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+Debugging process:
+- Analyze error messages and logs
+- Check recent code changes
+- Form and test hypotheses
+- Add strategic debug logging
+- Inspect variable states
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+- Prevention recommendations
+
+Focus on fixing the underlying issue, not the symptoms.
+```
+
+### Data Scientist
+
+```markdown
+---
+name: data-scientist
+description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
+---
+
+You are a data scientist specializing in SQL and BigQuery analysis.
+
+When invoked:
+1. Understand the data analysis requirement
+2. Write efficient SQL queries
+3. Use BigQuery command line tools (bq) when appropriate
+4. Analyze and summarize results
+5. Present findings clearly
+
+Key practices:
+- Write optimized SQL queries with proper filters
+- Use appropriate aggregations and joins
+- Include comments explaining complex logic
+- Format results for readability
+- Provide data-driven recommendations
+
+For each analysis:
+- Explain the query approach
+- Document any assumptions
+- Highlight key findings
+- Suggest next steps based on data
+
+Always ensure queries are efficient and cost-effective.
+```
+
+## Subagent Creation Workflow
+
+### Step 1: Decide the Scope
+
+- **Project-level** (`.cursor/agents/`): For codebase-specific agents shared with team
+- **User-level** (`~/.cursor/agents/`): For personal agents across all projects
+
+### Step 2: Create the File
+
+```bash
+# For project-level
+mkdir -p .cursor/agents
+touch .cursor/agents/my-agent.md
+
+# For user-level
+mkdir -p ~/.cursor/agents
+touch ~/.cursor/agents/my-agent.md
+```
+
+### Step 3: Define Configuration
+
+Write the frontmatter with the required fields (`name` and `description`).
+
+### Step 4: Write the System Prompt
+
+The body becomes the system prompt. Be specific about:
+- What the agent should do when invoked
+- Outcomes, constraints, and how to verify (exact steps only for fragile operations); reviewer and judge agents flag only correctness and requirement gaps
+- Output format and structure
+- Any constraints or guidelines
+
+### Step 5: Test the Agent
+
+Ask the AI to use your new agent:
+
+```
+Use the my-agent subagent to [task description]
+```
+
+## Best Practices
+
+1. **Design focused subagents**: Each should excel at one specific task
+2. **Write detailed descriptions**: Include trigger terms so the AI knows when to delegate
+3. **Check into version control**: Share project subagents with your team
+4. **Describe when delegation pays**: the description is what the main agent reads to decide; state the track size and independence it needs, not a blanket "use proactively"
+
+## Troubleshooting
+
+### Subagent Not Found
+- Ensure file is in `.cursor/agents/` or `~/.cursor/agents/`
+- Check file has `.md` extension
+- Verify YAML frontmatter syntax is valid

package/skills-cursor/migrate-to-skills/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: migrate-to-skills
+description: Convert 'Applied intelligently' Cursor rules (.cursor/rules/*.mdc) and slash commands (.cursor/commands/*.md) to Agent Skills format (.cursor/skills/). Use when the user wants to migrate rules or commands to skills, convert .mdc rules to SKILL.md format, or consolidate commands into the skills directory.
+disable-model-invocation: true
+effort: low
+---
+# Migrate Rules and Slash Commands to Skills
+
+Convert Cursor rules ("Applied intelligently") and slash commands to Agent Skills format.
+
+Copy each body verbatim — byte for byte, whitespace and typos included. The content is the user's, and an exact copy is what makes the migration reversible.
+
+## Locations
+
+| Level | Source | Destination |
+|-------|--------|-------------|
+| Project | `{workspaceFolder}/**/.cursor/rules/*.mdc`, `{workspaceFolder}/.cursor/commands/*.md` |
+| User | `~/.cursor/commands/*.md` |
+
+Notes:
+- Cursor rules inside the project can live in nested directories; glob `**/.cursor/rules/*.mdc` from the workspace root so none are missed.
+- Ignore anything in ~/.cursor/worktrees
+- Ignore anything in ~/.cursor/skills-cursor. This is reserved for Cursor's internal built-in skills and is managed automatically by the system.
+
+## Finding Files to Migrate
+
+**Rules**: Migrate if rule has a `description` but NO `globs` and NO `alwaysApply: true`.
+
+**Commands**: Migrate all - they're plain markdown without frontmatter.
+
+## Conversion Format
+
+### Rules: .mdc → SKILL.md
+
+```markdown
+# Before: .cursor/rules/my-rule.mdc
+---
+description: What this rule does
+globs:
+alwaysApply: false
+---
+# Title
+Body content...
+```
+
+```markdown
+# After: .cursor/skills/my-rule/SKILL.md
+---
+name: my-rule
+description: What this rule does
+---
+# Title
+Body content...
+```
+
+Changes: Add `name` field, remove `globs`/`alwaysApply`, keep body exactly.
+
+### Commands: .md → SKILL.md
+
+```markdown
+# Before: .cursor/commands/commit.md
+# Commit current work
+Instructions here...
+```
+
+```markdown
+# After: .cursor/skills/commit/SKILL.md
+---
+name: commit
+description: Commit current work with standardized message format
+disable-model-invocation: true
+---
+# Commit current work
+Instructions here...
+```
+
+Changes: Add frontmatter with `name` (from filename), `description` (infer from content), and `disable-model-invocation: true`, keep body exactly.
+
+**Note:** `disable-model-invocation: true` keeps the model from invoking the skill on its own and keeps its description out of the always-on skill roster that every request pays for. Slash commands are user-triggered from the `/` menu, so migrated commands carry it.
+
+## Notes
+
+- `name` must be lowercase with hyphens only
+- `description` is critical for skill discovery
+- The workflow below deletes originals after the skill file is written; the user can ask to undo, which restores them
+
+### Migrate a Rule (.mdc → SKILL.md)
+
+1. Read the rule file
+2. Extract the `description` from the frontmatter
+3. Extract the body content (everything after the closing `---` of the frontmatter)
+4. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .mdc)
+5. Write `SKILL.md` with new frontmatter (`name` and `description`) + the EXACT original body content (preserve all whitespace, formatting, code blocks verbatim)
+6. Delete the original rule file
+
+### Migrate a Command (.md → SKILL.md)
+
+1. Read the command file
+2. Extract description from the first heading (remove `#` prefix)
+3. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .md)
+4. Write `SKILL.md` with new frontmatter (`name`, `description`, and `disable-model-invocation: true`) + blank line + the EXACT original file content (preserve all whitespace, formatting, code blocks verbatim)
+5. Delete the original command file
+
+## Workflow
+
+Use the read, edit, and delete tools for these files rather than the terminal: they preserve bytes exactly and keep every change undoable.
+
+If you have the Task tool available, delegate the file work so the main context stays free of file contents. Dispatch three general-purpose subagents in parallel (not Explore — it is read-only), one each for project rules (`{workspaceFolder}/**/.cursor/rules/*.mdc`), user commands (`~/.cursor/commands/*.md`), and project commands (`{workspaceFolder}/**/.cursor/commands/*.md`). The work is mechanical; low effort is enough. Each subagent:
+  I. [ ] Finds files to migrate in its pattern
+  II. [ ] For rules, keeps only "applied intelligently" rules (has `description`, no `globs`, no `alwaysApply: true`). Commands are always migrated.
+  III. [ ] Lists the files to migrate. If empty, done.
+  IV. [ ] For each file, reads it, then writes the new skill file with the body verbatim.
+  V. [ ] Deletes the original file.
+  VI. [ ] Returns the migrated skill paths with their original paths.
+
+1. [ ] Create the skills directories if they don't exist (`.cursor/skills/` for project, `~/.cursor/skills/` for user)
+2. [ ] Dispatch the subagents and wait for all of them
+3. [ ] Summarize the results and tell the user they can ask you to undo the migration
+4. [ ] If asked to undo, reverse the steps to restore the original files
+
+If you don't have the Task tool available, do step 1, then I–V yourself across both project (`.cursor/`) and user (`~/.cursor/`) directories, then steps 3–4.

package/skills-cursor/shell/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: shell
+description: Run the rest of a /shell request as a literal shell command. Use only when the user explicitly invokes /shell and wants the following text executed directly in the terminal.
+disable-model-invocation: true
+effort: low
+---
+# Run Shell Commands
+
+Use this skill only when the user explicitly invokes `/shell`.
+
+## Behavior
+
+1. Treat all user text after the `/shell` invocation as the literal shell command to run.
+2. Execute that command immediately with the terminal tool.
+3. Do not rewrite, explain, or "improve" the command before running it.
+4. Do not inspect the repository first unless the command itself requires repository context.
+5. If the user invokes `/shell` without any following text, ask them which command to run.
+
+## Response
+
+- Run the command first.
+- Then briefly report the exit status and any important stdout or stderr.

package/skills-cursor/split-to-prs/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: split-to-prs
+description: >
+  Split current work into small reviewable PRs. Use when the user asks
+  to split a chat, branch, or change set. Whole dirty tree to one
+  merge-ready PR → workflow-release-prep.
+disable-model-invocation: true
+---
+# Split to PRs
+
+Turn one pile of work into a few small PRs.
+
+## Hard rules
+
+- Do not create branches, commit, push, or open PRs until the user approves the split plan.
+- Never discard user work. No destructive git commands (`reset --hard`, `clean -fdx`, branch deletion, force-push, history rewrite) without explicit approval.
+- Always save a recoverable snapshot before moving work around. This often starts from dirty work on `main`, so do not assume there is already a safe branch.
+- Stage only named files or hunks. No `git add .` / `git add -A`.
+
+## 1. Check the state
+
+Compare the current work to the repo's default branch, including committed and uncommitted changes. Summarize the real slices you see, and use the chat history to recover intent.
+
+## 2. Propose the split
+
+Use judgment on detail. Usually PR titles are enough. Add a one-line scope note only when a title is unclear. Show a Mermaid diagram when there are multiple slices.
+
+Default to independent PRs off the default branch. Stack PRs only when the dependency is real.
+
+Ask for approval before starting.
+
+## 3. Execute the split
+
+- If there is uncommitted work, save a recoverable snapshot without changing the working tree:
+
+  ```bash
+  SHA=$(git stash create "pre-split")
+  if [ -n "$SHA" ]; then
+    git update-ref "refs/backup/pre-split-$(date +%s)" "$SHA"
+  fi
+  ```
+
+- For each approved slice, create a branch from the right base, stage and commit only the planned files or hunks, then push and open the PR.
+
+## 4. Report back
+
+Keep it short: PR titles and URLs, plus anything left on the starting branch or working tree. Do not delete the backup ref or original branch unless the user asks.