shipshitdev/skill-capture

Skill Capture

When This Skill Activates

Activate when the user mentions ANY of these:

Explicit Requests

• "let's save this as a skill"
• "this workflow should be reusable"
• "capture this as a skill"
• "make this a skill"
• "turn this into a skill"
• "save this pattern"

Workflow Completion Signals

• Complex problem solved after multiple iterations
• Multi-step procedure successfully executed
• Valuable domain knowledge discovered through research
• Code pattern emerged that could benefit other projects

Learning Moments

• "this was tricky to figure out"
• "glad we finally got this working"
• "I wish I knew this earlier"
• "this should be documented"

---

Capture Process

Follow these 5 phases in order:

Phase 1: Identification

Review the conversation to identify capturable content:

What to Look For:

| Category | Example | |----------|---------| | Workflows | Multi-step procedures that took iterations to perfect | | Domain Knowledge | Information requiring research or expertise | | Problem Solutions | Approaches that resolved complex issues | | Code Patterns | Reusable patterns that could help other projects | | Decision Rationale | Architectural choices with clear reasoning |

Questions to Ask:

• Is this generalizable beyond this specific project?
• Would another agent session benefit from this knowledge?
• Did this require multiple iterations to get right?
• Is this non-obvious procedural knowledge?

Phase 2: Destination Planning

Determine where the skill should live:

1. Check if an existing skill should be updated
   - Glob for skills/*/SKILL.md
   - Read related skills to check for overlap

2. If creating new skill:
   - Choose descriptive kebab-case name
   - Create in skills/<skill-name>/ directory

Skill vs. Rule Decision:

| Create a Skill | Capture a Rule | |----------------|----------------| | Workflow with multiple steps | Single preference statement | | Procedural knowledge | "always/never do X" | | Domain expertise | Style/format preferences | | Code patterns with context | Import/naming conventions |

If it's a rule/preference, delegate to rules-capture skill instead.

Phase 3: Content Drafting

Transform conversational insights into SKILL.md format:

---
name: <skill-name>
description: <One sentence describing what the skill does and when to use it>
metadata:
  version: "1.0.0"
  tags: relevant, tags
---

# <Skill Title>

<Brief description of the skill's purpose>

---

## When to Use

<Clear triggers for when this skill should activate>

---

## Process

<Step-by-step workflow or procedure>

---

## Examples

<Concrete examples showing the skill in action>

---

## Integration

<How this skill works with other skills, if applicable>

Phase 4: Distillation

Extract and refine the content:

1. Extract the Final Approach - Capture only what worked, not the failed attempts
2. Generalize - Remove project-specific details that don't apply broadly
3. Add Context - Explain why certain approaches work, not just what to do
4. Include Examples - Add concrete examples that demonstrate usage

Checklist:

• [ ] Removed project-specific paths and names
• [ ] Generalized any hardcoded values
• [ ] Added explanatory context for non-obvious steps
• [ ] Included both good and bad examples where helpful
• [ ] Kept language in imperative form

Phase 5: Verification

Ensure the skill is ready for use:

Quality Checks:

| Check | Requirement | |-------|-------------| | Length | Under 500 lines (use references/ for large content) | | Frontmatter | Valid YAML with name and description | | Completeness | All sections have meaningful content | | Actionability | Instructions are specific enough to follow | | Formatting | Follows library patterns (see rules-capture for reference) |

Validation:

# Run the package script to validate
scripts/package_skill.py skills/<skill-name>

---

What to Capture

Good Candidates

• Workflows that took multiple iterations to get right
• Domain knowledge that required research
• Problem-solving approaches that worked
• Code patterns that could be reused across projects
• Decision rationale for architectural choices
• Integration patterns between tools or services
• Debugging approaches for specific technologies

Anti-Patterns (Do NOT Capture)

• One-off solutions specific to a single project
• Trivial fixes or obvious patterns
• Information already documented elsewhere
• Sensitive or proprietary information
• Incomplete workflows still being refined
• Preferences without procedural value (use rules-capture instead)

---

Output Structure

Create two files for each skill:

SKILL.md

See Phase 3 template above. Key principles:

• Use imperative form ("Do X" not "You should do X")
• Be specific about triggers and activation conditions
• Include concrete examples
• Reference any bundled resources

plugin.json

{
  "name": "<skill-name>",
  "version": "1.0.0",
  "description": "<Same description as SKILL.md frontmatter>",
  "author": {
    "name": "Ship Shit Dev",
    "email": "[email protected]",
    "url": "https://shipshit.dev"
  },
  "license": "MIT",
  "skills": "."
}

---

Integration

This skill works with:

| Skill | Integration | |-------|-------------| | rules-capture | Delegates preference capture; handles skill creation | | session-documenter | Skills captured during session are noted | | skill-creator | Uses creation patterns and validation | | docs | For formatting help with SKILL.md |

---

Example Interaction

Context: User spent 30 minutes debugging a NestJS queue integration issue. The solution involved specific configuration patterns.

User: "This was a pain to figure out. Let's save this for next time."

Agent:

I'll capture this as a skill. Let me analyze what we learned:

Capturable Knowledge:
- NestJS Bull queue configuration pattern
- Redis connection handling for queues
- Processor registration requirements

This would make a good standalone skill or could extend `nestjs-queue-architect`.

Let me check the existing skill...
[Reads skills/nestjs-queue-architect/SKILL.md]

The existing skill covers queue setup but not this specific debugging pattern.
I'll add a new "Troubleshooting" section.

Created: skills/nestjs-queue-architect/SKILL.md (updated)
- Added troubleshooting section
- Documented Redis connection requirements
- Added common error patterns

Should I also create session documentation for this debugging session?

---

Activation Triggers

The skill activates on these patterns:

# Explicit capture requests
(save|capture|turn|make).*(skill|reusable|pattern)
(this should be|let's make this).*(skill|documented|reusable)

# Workflow completion signals
(finally|glad).*(working|figured|solved)
(this was|that was).*(tricky|hard|difficult|complex)
(multiple|several).*(iterations|attempts|tries)

# Learning signals
(wish I knew|should have known|next time|for future)