diff --git a/.gitignore b/.gitignore index 7cfd02b..e873637 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ .DS_Store *.log node_modules/ +tmp/ +.tmp/ diff --git a/plugins/coding-tutor/skills/coding-tutor/SKILL.md b/plugins/coding-tutor/skills/coding-tutor/SKILL.md index 191e844..da3f2ec 100644 --- a/plugins/coding-tutor/skills/coding-tutor/SKILL.md +++ b/plugins/coding-tutor/skills/coding-tutor/SKILL.md @@ -1,51 +1,66 @@ --- name: coding-tutor -description: Personalized coding tutorials that build on your existing knowledge and use your actual codebase for examples. Creates a persistent learning trail that compounds over time using the power of AI, spaced repetition and quizes. +description: This skill should be used when creating personalized coding tutorials with spaced repetition quizzes. Triggers on "teach me", "create a tutorial", "quiz me", "help me learn", or "/teach-me". Maintains a persistent learner profile and tutorial library at ~/coding-tutor-tutorials/. +license: MIT +allowed-tools: + - Read + - Write + - Bash + - Edit +metadata: + version: 1.0.0 + category: learning --- -This skill creates personalized coding tutorials that evolve with the learner. Each tutorial builds on previous ones, uses real examples from the current codebase, and maintains a persistent record of concepts mastered. +# Personalized Coding Tutor -The user asks to learn something - either a specific concept or an open "teach me something new" request. +Create personalized coding tutorials that evolve with the learner, using real codebase examples and spaced repetition quizzes. + +## Contents + +- [Welcome New Learners](#welcome-new-learners) +- [Setup](#setup) +- [First Step: Know the Learner](#first-step-know-the-learner) +- [Teaching Workflow](#teaching-workflow) +- [Quiz Mode](#quiz-mode) +- [References](#references) ## Welcome New Learners -If `~/coding-tutor-tutorials/` does not exist, this is a new learner. Before running setup, introduce yourself: +If `~/coding-tutor-tutorials/` does not exist, introduce the skill: -> I'm your personal coding tutor. I create tutorials tailored to you - using real code from your projects, building on what you already know, and tracking your progress over time. +> I'm a personal coding tutor. I create tutorials tailored to the learner - using real code from projects, building on existing knowledge, and tracking progress over time. > -> All your tutorials live in one central library (`~/coding-tutor-tutorials/`) that works across all your projects. Use `/teach-me` to learn something new, `/quiz-me` to test your retention with spaced repetition. +> All tutorials live in one central library (`~/coding-tutor-tutorials/`) that works across all projects. Use `/teach-me` to learn something new, `/quiz-me` to test retention with spaced repetition. Then proceed with setup and onboarding. -## Setup: Ensure Tutorials Repo Exists +## Setup -**Before doing anything else**, run the setup script to ensure the central tutorials repository exists: +**Run before doing anything else:** ```bash python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/setup_tutorials.py ``` -This creates `~/coding-tutor-tutorials/` if it doesn't exist. All tutorials and the learner profile are stored there, shared across all your projects. - -## First Step: Know Your Learner - -**Always start by reading `~/coding-tutor-tutorials/learner_profile.md` if it exists.** This profile contains crucial context about who you're teaching - their background, goals, and personality. Use it to calibrate everything: what analogies will land, how fast to move, what examples resonate. +This creates `~/coding-tutor-tutorials/` if it doesn't exist. All tutorials and learner profiles are stored there, shared across all projects. -If no tutorials exist in `~/coding-tutor-tutorials/` AND no learner profile exists at `~/coding-tutor-tutorials/learner_profile.md`, this is a brand new learner. Before teaching anything, you need to understand who you're teaching. +## First Step: Know the Learner -**Onboarding Interview:** +**Read `~/coding-tutor-tutorials/learner_profile.md` first if it exists.** This profile contains context about the learner being taught - background, goals, and personality. Use it to calibrate analogies, pacing, and examples. -Ask these three questions, one at a time. Wait for each answer before asking the next. +If no tutorials or profile exist, this is a new learner. Conduct onboarding before teaching. -1. **Prior exposure**: What's your background with programming? - Understand if they've built anything before, followed tutorials, or if this is completely new territory. +### Onboarding Interview -2. **Ambitious goal**: This is your private AI tutor whose goal is to make you a top 1% programmer. Where do you want this to take you? - Understand what success looks like for them: a million-dollar product, a job at a company they admire, or something else entirely. +Ask these questions one at a time, waiting for each answer: -3. **Who are you**: Tell me a bit about yourself - imagine we just met at a coworking space. - Get context that shapes how to teach them. +1. **Prior exposure**: What programming background exists? Any previous builds, tutorials followed, or completely new? +2. **Ambitious goal**: Where should this private AI tutor lead? A million-dollar product, a dream job, or something else? +3. **Who are you**: Context that shapes teaching approach - like meeting at a coworking space +4. **Optional**: One additional question if it enriches understanding -4. **Optional**: Based on the above answers, you may ask upto one optional 4th question if it will make your understanding of the learner richer. - -After gathering responses, create `~/coding-tutor-tutorials/learner_profile.md` and put the interview Q&A there (along with your commentary): +After gathering responses, create `~/coding-tutor-tutorials/learner_profile.md`: ```yaml --- @@ -53,162 +68,55 @@ created: DD-MM-YYYY last_updated: DD-MM-YYYY --- -**Q1. ** -**Answer**. -**your internal commentary** - -**Q2. ** -**Answer**. -**your internal commentary** +**Q1. ** +**Answer**. +**Commentary**: -**Q3. ** -**Answer**. -**your internal commentary** +**Q2. ** +**Answer**. +**Commentary**: -**Q4. +**Q3. ** +**Answer**. +**Commentary**: ``` -## Teaching Philosophy - -Our general goal is to take the user from newbie to a senior engineer in record time. One at par with engineers at companies like 37 Signals or Vercel. - -Before creating a tutorial, make a plan by following these steps: - -- **Load learner context**: Read `~/coding-tutor-tutorials/learner_profile.md` to understand who you're teaching - their background, goals, and personality. -- **Survey existing knowledge**: Run `python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/index_tutorials.py` to understand what concepts have been covered, at what depth, and how well they landed (understanding scores). Optionally, dive into particular tutorials in `~/coding-tutor-tutorials/` to read them. -- **Identify the gap**: What's the next concept that would be most valuable? Consider both what they've asked for AND what naturally follows from their current knowledge. Think of a curriculum that would get them from their current point to Senior Engineer - what should be the next 3 topics they need to learn to advance their programming knowledge in this direction? -- **Find the anchor**: Locate real examples in the codebase that demonstrate this concept. Learning from abstract examples is forgettable; learning from YOUR code is sticky. -- **(Optional) Use ask-user-question tool**: Ask clarifying questions to the learner to understand their intent, goals or expectations if it'll help you make a better plan. - -Then show this curriculum plan of **next 3 TUTORIALS** to the user and proceed to the tutorial creation step only if the user approves. If the user rejects, create a new plan using steps mentioned above. - -## Tutorial Creation - -Each tutorial is a markdown file in `~/coding-tutor-tutorials/` with this structure: -```yaml ---- -concepts: [primary_concept, related_concept_1, related_concept_2] -source_repo: my-app # Auto-detected: which repo this tutorial's examples come from -description: One-paragraph summary of what this tutorial covers -understanding_score: null # null until quizzed, then 1-10 based on quiz performance -last_quizzed: null # null until first quiz, then DD-MM-YYYY -prerequisites: [~/coding-tutor-tutorials/tutorial_1_name.md, ~/coding-tutor-tutorials/tutorial_2_name.md, (upto 3 other existing tutorials)] -created: DD-MM-YYYY -last_updated: DD-MM-YYYY ---- - -Full contents of tutorial go here - ---- +## Teaching Workflow -## Q&A +1. **Load context**: Read learner profile and index existing tutorials +2. **Plan curriculum**: Identify gaps, find codebase anchors, plan next 3 tutorials +3. **Get approval**: Present plan to learner before proceeding +4. **Create tutorial**: Use template with real codebase examples +5. **Update Q&A**: Append clarifying questions to tutorial's Q&A section -Cross-questions during learning go here. +See [references/teaching-philosophy.md](./references/teaching-philosophy.md) for detailed guidance. -## Quiz History - -Quiz sessions recorded here. -``` - -Run `scripts/create_tutorial.py` like this to create a new tutorial with template: +### Creating Tutorials ```bash python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/create_tutorial.py "Topic Name" --concepts "Concept1,Concept2" ``` -This creates an empty template of the tutorial. Then you should edit the newly created file to write in the actual tutorial. -Qualities of a great tutorial should: - -- **Start with the "why"**: Not "here's how callbacks work" but "here's the problem in your code that callbacks solve" -- **Use their code**: Every concept demonstrated with examples pulled from the actual codebase. Reference specific files and line numbers. -- **Build mental models**: Diagrams, analogies, the underlying "shape" of the concept - not just syntax, ELI5 -- **Predict confusion**: Address the questions they're likely to ask before they ask them, don't skim over things, don't write in a notes style -- **End with a challenge**: A small exercise they could try in this codebase to cement understanding - -### Tutorial Writing Style - -Write personal tutorials like the best programming educators: Julia Evans, Dan Abramov. Not like study notes or documentation. There's a difference between a well-structured tutorial and one that truly teaches. - -- Show the struggle - "Here's what you might try... here's why it doesn't work... here's the insight that unlocks it." -- Fewer concepts, more depth - A tutorial that teaches 3 things deeply beats one that mentions 10 things. -- Tell stories - a great tutorial is one coherent story, dives deep into a single concept, using storytelling techniques that engage readers - -We should make the learner feel like Julia Evans or Dan Abramov is their private tutor. - -Note: If you're not sure about a fact or capability or new features/APIs, do web research, look at documentation to make sure you're teaching accurate up-to-date things. NEVER commit the sin of teaching something incorrect. - -## The Living Tutorial - -Tutorials aren't static documents - they evolve: - -- **Q&A is mandatory**: When the learner asks ANY clarifying question about a tutorial, you MUST append it to the tutorial's `## Q&A` section. This is not optional - these exchanges are part of their personalized learning record and improve future teaching. -- If the learner says they can't follow the tutorial or need you to take a different approach, update the tutorial like they ask -- Update `last_updated` timestamp -- If a question reveals a gap in prerequisites, note it for future tutorial planning - -Note: `understanding_score` is only updated through Quiz Mode, not during teaching. - -## What Makes Great Teaching -**DO**: Meet them where they are. Use their vocabulary. Reference their past struggles. Make connections to concepts they already own. Be encouraging but honest about complexity. - -**DON'T**: Assume knowledge not demonstrated in previous tutorials. Use generic blog-post examples when codebase examples exist. Overwhelm with every edge case upfront. Be condescending about gaps. - -**CALIBRATE**: A learner with 3 tutorials is different from one with 30. Early tutorials need more scaffolding and encouragement. Later tutorials can move faster and reference the shared history you've built. - -Remember: The goal isn't to teach programming in the abstract. It's to teach THIS person, using THEIR code, building on THEIR specific journey. Every tutorial should feel like it was written specifically for them - because it was. +See [references/tutorial-template.md](./references/tutorial-template.md) for template structure and writing style. ## Quiz Mode -Tutorials teach. Quizzes verify. The score should reflect what the learner actually retained, not what was presented to them. +Tutorials teach. Quizzes verify understanding through spaced repetition. **Triggers:** -- Explicit: "Quiz me on React hooks" → quiz that specific concept -- Open: "Quiz me on something" → run `python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/quiz_priority.py` to get a prioritized list based on spaced repetition, then choose what to quiz - -**Spaced Repetition:** - -When the user requests an open quiz, the priority script uses spaced repetition intervals to surface: -- Never-quizzed tutorials (need baseline assessment) -- Low-scored concepts that are overdue for review -- High-scored concepts whose review interval has elapsed +- Explicit: "Quiz me on React hooks" → quiz that concept +- Open: "Quiz me on something" → use priority script -The script uses Fibonacci-ish intervals: score 1 = review in 2 days, score 5 = 13 days, score 8 = 55 days, score 10 = 144 days. This means weak concepts get drilled frequently while mastered ones fade into long-term review. - -The script gives you an ordered list with `understanding_score` and `last_quizzed` for each tutorial. Use this to make an informed choice about what to quiz, and explain to the learner why you picked that concept ("You learned callbacks 5 days ago but scored 4/10 - let's see if it's sticking better now"). - -**Philosophy:** - -A quiz isn't an exam - it's a conversation that reveals understanding. Ask questions that expose mental models, not just syntax recall. The goal is to find the edges of their knowledge: where does solid understanding fade into uncertainty? - -**Ask only 1 question at a time.** Wait for the learner's answer before asking the next question. - -Mix question types based on what the concept demands: -- Conceptual ("when would you use X over Y?") -- Code reading ("what does this code in your app do?") -- Code writing ("write a scope that does X") -- Debugging ("what's wrong here?") - -Use their codebase for examples whenever possible. "What does line 47 of `app/models/user.rb` do?" is more valuable than abstract snippets. - -**Scoring:** - -After the quiz, update `understanding_score` honestly: -- **1-3**: Can't recall the concept, needs re-teaching -- **4-5**: Vague memory, partial answers -- **6-7**: Solid understanding, minor gaps -- **8-9**: Strong grasp, handles edge cases -- **10**: Could teach this to someone else - -Also update `last_quizzed: DD-MM-YYYY` in the frontmatter. +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/quiz_priority.py +``` -**Recording:** +See [references/quiz-mode.md](./references/quiz-mode.md) for spaced repetition intervals, scoring rubric, and recording format. -Append to the tutorial's `## Quiz History` section: -``` -### Quiz - DD-MM-YYYY -**Q:** [Question asked] -**A:** [Brief summary of their response and what it revealed about understanding] -Score updated: 5 → 7 -``` +## References -This history helps future quizzes avoid repetition and track progression over time. +| File | Purpose | +|------|---------| +| [teaching-philosophy.md](./references/teaching-philosophy.md) | Pre-tutorial planning and teaching principles | +| [tutorial-template.md](./references/tutorial-template.md) | Template structure and writing style | +| [quiz-mode.md](./references/quiz-mode.md) | Spaced repetition and scoring details | diff --git a/plugins/coding-tutor/skills/coding-tutor/references/quiz-mode.md b/plugins/coding-tutor/skills/coding-tutor/references/quiz-mode.md new file mode 100644 index 0000000..b6ade30 --- /dev/null +++ b/plugins/coding-tutor/skills/coding-tutor/references/quiz-mode.md @@ -0,0 +1,74 @@ +# Quiz Mode Reference + +Tutorials teach. Quizzes verify. Scores reflect what learners actually retained, not what was presented. + +## Triggers + +- **Explicit**: "Quiz me on React hooks" → quiz that specific concept +- **Open**: "Quiz me on something" → run priority script for spaced repetition selection + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/quiz_priority.py +``` + +## Spaced Repetition + +The priority script uses spaced repetition intervals to surface: +- Never-quizzed tutorials (need baseline assessment) +- Low-scored concepts overdue for review +- High-scored concepts whose review interval elapsed + +**Fibonacci-ish intervals:** +| Score | Review Interval | +|-------|-----------------| +| 1 | 2 days | +| 5 | 13 days | +| 8 | 55 days | +| 10 | 144 days | + +Weak concepts get drilled frequently; mastered ones fade into long-term review. + +Explain quiz selection to learners: "You learned callbacks 5 days ago but scored 4/10 - let's see if it's sticking better now" + +## Quiz Philosophy + +A quiz is a conversation revealing understanding, not an exam. Ask questions that expose mental models, not just syntax recall. Find the edges of knowledge: where does solid understanding fade into uncertainty? + +**Ask only 1 question at a time.** Wait for the answer before asking the next. + +## Question Types + +Mix based on what the concept demands: +- **Conceptual**: "When would you use X over Y?" +- **Code reading**: "What does this code in your app do?" +- **Code writing**: "Write a scope that does X" +- **Debugging**: "What's wrong here?" + +Use learner's codebase for examples whenever possible. + +## Scoring + +After the quiz, update `understanding_score` honestly: + +| Score | Meaning | +|-------|---------| +| 1-3 | Can't recall concept, needs re-teaching | +| 4-5 | Vague memory, partial answers | +| 6-7 | Solid understanding, minor gaps | +| 8-9 | Strong grasp, handles edge cases | +| 10 | Could teach this to someone else | + +Update `last_quizzed: DD-MM-YYYY` in frontmatter. + +## Recording Quiz History + +Append to tutorial's `## Quiz History` section: + +```markdown +### Quiz - DD-MM-YYYY +**Q:** [Question asked] +**A:** [Brief summary of response and what it revealed about understanding] +Score updated: 5 → 7 +``` + +This history helps future quizzes avoid repetition and track progression. diff --git a/plugins/coding-tutor/skills/coding-tutor/references/teaching-philosophy.md b/plugins/coding-tutor/skills/coding-tutor/references/teaching-philosophy.md new file mode 100644 index 0000000..c549c09 --- /dev/null +++ b/plugins/coding-tutor/skills/coding-tutor/references/teaching-philosophy.md @@ -0,0 +1,36 @@ +# Teaching Philosophy Reference + +Take learners from newbie to senior engineer level (comparable to engineers at 37 Signals or Vercel). + +## Pre-Tutorial Planning + +Before creating a tutorial: + +1. **Load learner context**: Read `~/coding-tutor-tutorials/learner_profile.md` to understand background, goals, and personality +2. **Survey existing knowledge**: Run `python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/index_tutorials.py` to understand covered concepts, depth, and understanding scores +3. **Identify the gap**: What concept would be most valuable next? Consider both requests AND natural progression. Plan the next 3 topics toward Senior Engineer level +4. **Find the anchor**: Locate real codebase examples. Learning from YOUR code is sticky; abstract examples are forgettable +5. **Clarify intent** (optional): Use ask-user-question tool if needed + +Present curriculum plan of **next 3 tutorials** to the learner. Proceed only on approval. + +## What Makes Great Teaching + +**DO:** +- Meet learners where they are +- Use their vocabulary +- Reference past struggles +- Make connections to concepts they already own +- Be encouraging but honest about complexity + +**DON'T:** +- Assume knowledge not demonstrated in previous tutorials +- Use generic blog-post examples when codebase examples exist +- Overwhelm with every edge case upfront +- Be condescending about gaps + +**CALIBRATE:** +- Learner with 3 tutorials: needs more scaffolding and encouragement +- Learner with 30 tutorials: can move faster and reference shared history + +The goal: teach THIS person, using THEIR code, building on THEIR specific journey. Every tutorial should feel personally written because it was. diff --git a/plugins/coding-tutor/skills/coding-tutor/references/tutorial-template.md b/plugins/coding-tutor/skills/coding-tutor/references/tutorial-template.md new file mode 100644 index 0000000..29dd105 --- /dev/null +++ b/plugins/coding-tutor/skills/coding-tutor/references/tutorial-template.md @@ -0,0 +1,69 @@ +# Tutorial Template Reference + +## Tutorial File Structure + +Each tutorial is a markdown file in `~/coding-tutor-tutorials/`: + +```yaml +--- +concepts: [primary_concept, related_concept_1, related_concept_2] +source_repo: my-app # Auto-detected: which repo examples come from +description: One-paragraph summary of what this tutorial covers +understanding_score: null # null until quizzed, then 1-10 based on quiz performance +last_quizzed: null # null until first quiz, then DD-MM-YYYY +prerequisites: [~/coding-tutor-tutorials/tutorial_1_name.md, ~/coding-tutor-tutorials/tutorial_2_name.md] +created: DD-MM-YYYY +last_updated: DD-MM-YYYY +--- + +Full contents of tutorial go here + +--- + +## Q&A + +Cross-questions during learning go here. + +## Quiz History + +Quiz sessions recorded here. +``` + +## Creating Tutorials + +```bash +python3 ${CLAUDE_PLUGIN_ROOT}/skills/coding-tutor/scripts/create_tutorial.py "Topic Name" --concepts "Concept1,Concept2" +``` + +This creates an empty template. Edit the file to write the actual tutorial. + +## Qualities of Great Tutorials + +- **Start with the "why"**: Not "here's how callbacks work" but "here's the problem in your code that callbacks solve" +- **Use their code**: Every concept demonstrated with examples from the actual codebase. Reference specific files and line numbers +- **Build mental models**: Diagrams, analogies, the underlying "shape" of the concept (not just syntax). ELI5 +- **Predict confusion**: Address questions before they're asked. Don't skim or write in notes style +- **End with a challenge**: A small exercise in this codebase to cement understanding + +## Writing Style + +Write like the best programming educators: Julia Evans, Dan Abramov. Not like study notes or documentation. + +- **Show the struggle**: "Here's what you might try... here's why it doesn't work... here's the insight that unlocks it." +- **Fewer concepts, more depth**: 3 things taught deeply beats 10 things mentioned +- **Tell stories**: One coherent story diving deep into a single concept + +The learner should feel like Julia Evans or Dan Abramov is their private tutor. + +**Accuracy requirement**: If unsure about facts, APIs, or features, do web research. Never teach something incorrect. + +## The Living Tutorial + +Tutorials evolve: + +- **Q&A is mandatory**: When learners ask ANY clarifying question, append to `## Q&A` section. These exchanges improve future teaching +- Update tutorials when learners request different approaches +- Update `last_updated` timestamp +- Note prerequisite gaps for future planning + +Note: `understanding_score` is only updated through Quiz Mode, not during teaching. diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 1328545..d1ac125 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -102,6 +102,8 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in ## Skills +For detailed skill documentation and installation into other AI coding agents, see [docs/skills.md](docs/skills.md). + ### Architecture & Design | Skill | Description | diff --git a/plugins/compound-engineering/docs/agent-native-architecture_skill.md b/plugins/compound-engineering/docs/agent-native-architecture_skill.md new file mode 100644 index 0000000..c0619ac --- /dev/null +++ b/plugins/compound-engineering/docs/agent-native-architecture_skill.md @@ -0,0 +1,140 @@ +# Agent-Native Architecture Skill + +Build AI agents using prompt-native architecture where features are defined in prompts, not code. + +## What This Skill Does + +This skill provides comprehensive guidance for building prompt-native agents: + +- **Prompt-native philosophy** - Features as prompts, not code workflows +- **MCP tool design** - Primitive tools that enable capability, not encode behavior +- **System prompts** - Define outcomes, trust the agent's intelligence +- **Self-modification** - Enable agents to safely evolve themselves +- **Action parity** - Ensure agents can do everything users can do +- **Context injection** - Inject runtime app state into agent prompts + +## Common Workflows + +### 1. Design Primitive Tools +Create tools that enable capability, not encode workflows. + +```typescript +// RIGHT - primitives that enable capability +const tools = [ + tool("read_file", "Read any file", { path: z.string() }, ...), + tool("write_file", "Write any file", { path: z.string(), content: z.string() }, ...), + tool("list_files", "List directory", { path: z.string() }, ...), +]; + +// WRONG - workflow encoded in tool +tool("process_feedback", async ({ message }) => { + const category = categorize(message); // Your code + const priority = calculatePriority(message); // Your code + await store(message, category, priority); // Your code +}); +``` + +### 2. Write Behavior in System Prompt +Define outcomes, let the agent figure out HOW. + +```markdown +## Your Responsibilities +When asked to organize content, you should: +1. Read existing files to understand the structure +2. Analyze what organization makes sense +3. Create appropriate pages using write_file +4. Use your judgment about layout and formatting + +You decide the structure. Make it good. +``` + +### 3. Ensure Action Parity +Every UI action has a corresponding agent tool. + +```markdown +- [ ] Every UI action has a corresponding agent tool +- [ ] If UI can edit or delete, agent can too +- [ ] The "write something to [app location]" test passes +``` + +### 4. Inject Dynamic Context +Include available resources and capabilities in system prompt. + +```markdown +## Available Resources +- Feed entries: 47 items +- Draft insights: 3 items +- Recent activity: Updated 2 hours ago + +## What You Can Do +- write_to_feed: Publish content to the main feed +- create_insight: Save a new insight draft +``` + +### 5. Add Self-Modification (Advanced) +Enable agents to safely evolve their own code. + +```markdown +Requirements: +- Approval gates for code changes +- Auto-commit before modifications (rollback capability) +- Health checks after changes +- Build verification before restart +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install agent-native-architecture --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install agent-native-architecture --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install agent-native-architecture --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install agent-native-architecture --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/andrew-kane-gem-writer_skill.md b/plugins/compound-engineering/docs/andrew-kane-gem-writer_skill.md new file mode 100644 index 0000000..cc582d1 --- /dev/null +++ b/plugins/compound-engineering/docs/andrew-kane-gem-writer_skill.md @@ -0,0 +1,135 @@ +# Andrew Kane Gem Writer Skill + +Write Ruby gems following Andrew Kane's proven patterns from 100+ gems with 374M+ downloads. + +## What This Skill Does + +This skill applies battle-tested patterns from gems like Searchkick, PgHero, and Chartkick: + +- **Entry point structure** - Proper lib/gemname.rb organization +- **Class macro DSL** - The signature Kane pattern for configuration +- **Rails integration** - Safe ActiveSupport.on_load patterns +- **Zero dependencies** - Minimal runtime dependencies philosophy +- **Configuration** - Class accessor patterns, not Configuration objects +- **Testing** - Minitest-only testing patterns + +## Common Workflows + +### 1. Create Gem Entry Point +Structure the main gem file correctly. + +```ruby +# lib/gemname.rb +require "forwardable" +require_relative "gemname/model" +require_relative "gemname/version" +require_relative "gemname/railtie" if defined?(Rails) + +module GemName + class Error < StandardError; end + + class << self + attr_accessor :timeout, :logger + end + + self.timeout = 10 +end +``` + +### 2. Implement Class Macro DSL +Create the signature single-method configuration pattern. + +```ruby +class Product < ApplicationRecord + searchkick word_start: [:name] # One method call configures everything +end +``` + +### 3. Add Rails Integration +Use ActiveSupport.on_load, never require Rails directly. + +```ruby +ActiveSupport.on_load(:active_record) do + extend GemName::Model +end +``` + +### 4. Configure Without Objects +Use class accessors instead of Configuration classes. + +```ruby +module GemName + class << self + attr_accessor :timeout, :logger + end + self.timeout = 10 +end +``` + +### 5. Write Minitest Tests +Follow the Minitest-only testing pattern. + +```ruby +class ModelTest < Minitest::Test + def test_basic_functionality + assert_equal expected, actual + end +end +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install andrew-kane-gem-writer --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install andrew-kane-gem-writer --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install andrew-kane-gem-writer --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install andrew-kane-gem-writer --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/compound-docs_skill.md b/plugins/compound-engineering/docs/compound-docs_skill.md new file mode 100644 index 0000000..5288e50 --- /dev/null +++ b/plugins/compound-engineering/docs/compound-docs_skill.md @@ -0,0 +1,110 @@ +# Compound Docs Skill + +Document solved problems as categorized knowledge base entries with YAML frontmatter for fast lookup and pattern recognition. + +## What This Skill Does + +This skill captures and organizes problem solutions to build searchable institutional knowledge: + +- **Auto-detection** - Triggers on phrases like "that worked" or "it's fixed" +- **Categorized storage** - Organizes by problem type (performance, configuration, integration, type errors) +- **YAML validation** - Enforces schema compliance before saving +- **Cross-referencing** - Links related issues and detects patterns +- **Decision menu** - Guides next steps after documentation + +## Common Workflows + +### 1. Document a Fix After Confirmation +When you hear "that worked" or similar confirmation phrases. + +```markdown +# The skill auto-invokes and creates: +docs/solutions/performance-issues/n-plus-one-briefs.md +``` + +### 2. Run Manual Documentation +Use the /doc-fix command for intentional documentation. + +```bash +/doc-fix +``` + +### 3. Search Existing Solutions +Find previously documented solutions. + +```bash +grep -l 'root_cause: connection' docs/solutions/**/*.md +``` + +### 4. Add to Required Reading +Mark critical solutions for team awareness. + +```markdown +# After documentation, select option 2: +"Add to Required Reading" +``` + +### 5. Create a Skill from Pattern +When a solution becomes a recurring pattern. + +```markdown +# After documentation, select option 5: +"Create new skill" +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install compound-docs --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install compound-docs --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install compound-docs --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install compound-docs --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/create-agent-skills_skill.md b/plugins/compound-engineering/docs/create-agent-skills_skill.md new file mode 100644 index 0000000..6c379b4 --- /dev/null +++ b/plugins/compound-engineering/docs/create-agent-skills_skill.md @@ -0,0 +1,136 @@ +# Creating Agent Skills Skill + +Create, write, and refine Claude Code Skills following Anthropic's official specification and best practices. + +## What This Skill Does + +This skill teaches how to create effective Claude Code Skills: + +- **Structure guidance** - YAML frontmatter and markdown body format +- **Progressive disclosure** - Keep SKILL.md lean, use references +- **Naming conventions** - Gerund form (verb + -ing) patterns +- **Effective descriptions** - Trigger keywords and discovery +- **Audit skills** - Check against best practices rubric +- **Common patterns** - Templates, workflows, conditionals + +## Common Workflows + +### 1. Create a New Skill +Start with proper YAML frontmatter and structure. + +```markdown +--- +name: your-skill-name +description: [What it does]. Use when [trigger conditions]. +--- + +# Your Skill Name + +## Quick Start +[Immediate actionable example] + +## Instructions +[Core guidance] + +## Examples +[Input/output pairs] +``` + +### 2. Write Effective Descriptions +Include what the skill does AND when to use it. + +```yaml +# Good: +description: Extracts text and tables from PDF files. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. + +# Bad: +description: Helps with documents +``` + +### 3. Add Reference Files +Move detailed content to separate files for token efficiency. + +```markdown +For API reference, see [REFERENCE.md](REFERENCE.md). +For form filling guide, see [FORMS.md](FORMS.md). +``` + +### 4. Audit an Existing Skill +Check against the best practices rubric. + +```markdown +- [ ] Valid YAML frontmatter (name + description) +- [ ] Description includes trigger keywords +- [ ] Uses standard markdown headings +- [ ] SKILL.md under 500 lines +- [ ] Examples are concrete, not abstract +``` + +### 5. Add a Workflow Pattern +Structure complex multi-step tasks. + +```markdown +## Migration Workflow + +Copy this checklist: +- [ ] Step 1: Backup database +- [ ] Step 2: Run migration script +- [ ] Step 3: Validate output +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install create-agent-skills --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install create-agent-skills --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install create-agent-skills --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install create-agent-skills --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/dhh-rails-style_skill.md b/plugins/compound-engineering/docs/dhh-rails-style_skill.md new file mode 100644 index 0000000..3b52f09 --- /dev/null +++ b/plugins/compound-engineering/docs/dhh-rails-style_skill.md @@ -0,0 +1,147 @@ +# DHH Rails Style Skill + +Write Ruby and Rails code in DHH's distinctive 37signals style, embodying REST purity, fat models, thin controllers, and the "clarity over cleverness" philosophy. + +## What This Skill Does + +This skill applies 37signals/DHH Rails conventions extracted from production codebases: + +- **REST mapping** - CRUD controllers over custom actions +- **Rich domain models** - Fat models over service objects +- **Concerns** - Horizontal code sharing via concerns +- **State as records** - Records instead of boolean columns +- **Database-backed** - Database for everything, no Redis +- **Vanilla Rails** - Build solutions before reaching for gems + +## Common Workflows + +### 1. Map Actions to REST +Convert custom actions to CRUD resources. + +```ruby +# Instead of: POST /cards/:id/close +# Use: POST /cards/:id/closure + +class Cards::ClosuresController < ApplicationController + def create + @card.close + redirect_to @card + end + + def destroy + @card.reopen + redirect_to @card + end +end +``` + +### 2. Create Model Concerns +Share behavior across models with concerns. + +```ruby +# app/models/concerns/closeable.rb +module Closeable + extend ActiveSupport::Concern + + def close + closures.create! + end + + def closed? + closures.exists? + end +end +``` + +### 3. Use State Records +Track state with records, not booleans. + +```ruby +# Instead of: card.closed = true +# Use: card.closures.create! + +Card.joins(:closure) # closed cards +Card.where.missing(:closure) # open cards +``` + +### 4. Add Authorization to Models +Put authorization logic on the User model. + +```ruby +class User < ApplicationRecord + def can_administer?(message) + message.creator == self || admin? + end +end +``` + +### 5. Apply Ruby Syntax Preferences +Use DHH's preferred syntax patterns. + +```ruby +# Symbol arrays with spaces inside brackets +before_action :set_message, only: %i[ show edit update destroy ] + +# Private method indentation + private + def set_message + @message = Message.find(params[:id]) + end +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install dhh-rails-style --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install dhh-rails-style --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install dhh-rails-style --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install dhh-rails-style --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/dspy-ruby_skill.md b/plugins/compound-engineering/docs/dspy-ruby_skill.md new file mode 100644 index 0000000..5248ff8 --- /dev/null +++ b/plugins/compound-engineering/docs/dspy-ruby_skill.md @@ -0,0 +1,146 @@ +# DSPy.rb Expert Skill + +Build type-safe, composable LLM applications in Ruby using the DSPy.rb framework. + +## What This Skill Does + +This skill provides comprehensive guidance for building LLM-powered applications in Ruby: + +- **Type-safe signatures** - Define input/output contracts with runtime type checking +- **Composable modules** - Build reusable, chainable LLM operations +- **Multiple predictors** - Choose Predict, ChainOfThought, ReAct, or CodeAct +- **Provider support** - Configure OpenAI, Anthropic, Gemini, or Ollama +- **Vision capabilities** - Process images alongside text +- **Testing patterns** - Write RSpec tests for LLM functionality + +## Common Workflows + +### 1. Create a Type-Safe Signature +Define an LLM task with typed inputs and outputs. + +```ruby +class EmailClassificationSignature < DSPy::Signature + description "Classify customer support emails" + + input do + const :email_subject, String + const :email_body, String + end + + output do + const :category, T.enum(["Technical", "Billing", "General"]) + const :priority, T.enum(["Low", "Medium", "High"]) + end +end +``` + +### 2. Build a Composable Module +Create reusable LLM operations that can be chained together. + +```ruby +class EmailProcessor < DSPy::Module + def initialize + super + @classifier = DSPy::Predict.new(EmailClassificationSignature) + end + + def forward(email_subject:, email_body:) + @classifier.forward(email_subject: email_subject, email_body: email_body) + end +end +``` + +### 3. Configure LLM Providers +Set up OpenAI, Anthropic, or local Ollama. + +```ruby +DSPy.configure do |c| + c.lm = DSPy::LM.new('anthropic/claude-3-5-sonnet-20241022', + api_key: ENV['ANTHROPIC_API_KEY']) +end +``` + +### 4. Process Images with Vision +Analyze images using multimodal capabilities. + +```ruby +result = predictor.forward( + image: DSPy::Image.from_file("path/to/image.jpg"), + question: "What objects are visible?" +) +``` + +### 5. Test LLM Applications +Write RSpec tests for LLM-powered features. + +```ruby +RSpec.describe EmailClassifier do + it 'classifies technical emails correctly' do + result = classifier.forward(email_subject: "Can't log in", email_body: "Unable to access") + expect(result[:category]).to eq('Technical') + end +end +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install dspy-ruby --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install dspy-ruby --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install dspy-ruby --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install dspy-ruby --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## Requirements + +- Ruby 3.1+ +- `gem install dspy` +- API key for chosen provider (OpenAI, Anthropic, Gemini, or Ollama) + +## License + +MIT diff --git a/plugins/compound-engineering/docs/every-style-editor_skill.md b/plugins/compound-engineering/docs/every-style-editor_skill.md new file mode 100644 index 0000000..7dc24cf --- /dev/null +++ b/plugins/compound-engineering/docs/every-style-editor_skill.md @@ -0,0 +1,118 @@ +# Every Style Editor Skill + +Review and edit copy to ensure adherence to Every's comprehensive style guide for grammar, punctuation, mechanics, and style compliance. + +## What This Skill Does + +This skill provides a systematic approach to copy editing: + +- **4-phase review** - Initial assessment, detailed line edit, mechanical review, recommendations +- **Style enforcement** - Apply Every's specific conventions consistently +- **Error tracking** - Find and document grammar, punctuation, and style violations +- **Actionable output** - Provide specific corrections with rule references +- **Voice preservation** - Maintain author's style while correcting issues + +## Common Workflows + +### 1. Review an Article +Run a complete 4-phase review on written content. + +```markdown +# Provide the article and request: +"Review this article against Every's style guide" + +# Output includes: +- Document summary +- Error count and corrections +- Recurring issues +- Style guide compliance checklist +``` + +### 2. Check Headlines +Verify title case and headline conventions. + +```markdown +# Headlines should be Title Case +# Body text uses sentence case +``` + +### 3. Fix Passive Voice +Convert passive constructions to active voice. + +```markdown +# Original: "The report was written by the team" +# Corrected: "The team wrote the report" +``` + +### 4. Apply Number Formatting +Ensure consistent number formatting. + +```markdown +# Spell out: one through nine +# Use numerals: 10 and above +``` + +### 5. Fix Em Dash Usage +Apply correct em dash formatting. + +```markdown +# Correct: word—word (no spaces) +# Wrong: word — word (with spaces) +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install every-style-editor --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install every-style-editor --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install every-style-editor --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install every-style-editor --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/file-todos_skill.md b/plugins/compound-engineering/docs/file-todos_skill.md new file mode 100644 index 0000000..891ee57 --- /dev/null +++ b/plugins/compound-engineering/docs/file-todos_skill.md @@ -0,0 +1,112 @@ +# File-Based Todo Tracking Skill + +Manage file-based todos in the `todos/` directory with YAML frontmatter for status, priority, and dependency tracking. + +## What This Skill Does + +This skill provides a structured system for tracking development work items: + +- **Todo creation** - Convert findings, feedback, or ideas into tracked work items +- **Status management** - Move items through pending → ready → complete lifecycle +- **Dependency tracking** - Block and unblock work based on prerequisites +- **Triage workflows** - Review and approve pending items +- **Code review integration** - Convert PR comments into actionable todos + +## Common Workflows + +### 1. Create a Todo from Code Review +Convert PR feedback into a tracked work item with priority and acceptance criteria. + +```bash +# Get next ID +ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}' + +# Create todo file +cp assets/todo-template.md todos/003-pending-p2-fix-validation.md +``` + +### 2. Triage Pending Items +Review pending todos and approve them for work. + +```bash +# List pending items +ls todos/*-pending-*.md + +# Approve by renaming pending → ready +mv todos/003-pending-p2-fix-validation.md todos/003-ready-p2-fix-validation.md +``` + +### 3. Complete a Todo +Mark work as done and update status. + +```bash +# Rename ready → complete +mv todos/003-ready-p2-fix-validation.md todos/003-complete-p2-fix-validation.md +``` + +### 4. Check Dependencies +Find items blocked by a specific todo. + +```bash +grep -l 'dependencies:.*"002"' todos/*-ready-*.md +``` + +### 5. Use Interactive Triage +Run the `/triage` slash command for a guided approval workflow. + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install file-todos --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install file-todos --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install file-todos --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install file-todos --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +MIT diff --git a/plugins/compound-engineering/docs/frontend-design_skill.md b/plugins/compound-engineering/docs/frontend-design_skill.md new file mode 100644 index 0000000..efd4287 --- /dev/null +++ b/plugins/compound-engineering/docs/frontend-design_skill.md @@ -0,0 +1,86 @@ +# Frontend Design Skill + +Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. + +## What This Skill Does + +This skill guides Claude in creating visually striking, memorable frontend interfaces. Instead of generating typical AI-generated designs with predictable patterns, it produces bold, intentional designs with: + +- **Distinctive typography** - Characterful fonts that elevate aesthetics +- **Cohesive color schemes** - Dominant colors with sharp accents +- **Purposeful motion** - Impactful animations and micro-interactions +- **Creative layouts** - Asymmetry, overlap, and grid-breaking elements + +## Common Workflows + +### 1. Creating a Landing Page +Ask Claude to build a landing page with a specific aesthetic direction (brutalist, art deco, minimalist luxury, etc.). + +### 2. Designing a Component Library +Generate a set of UI components with a unified design language. + +### 3. Building Interactive Widgets +Create widgets with engaging hover states and scroll-triggered animations. + +### 4. Prototyping a Web Application +Rapidly prototype app interfaces with production-quality code. + +### 5. Redesigning Existing Interfaces +Transform generic designs into distinctive, memorable experiences. + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install frontend-design --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install frontend-design --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install frontend-design --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install frontend-design --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +See LICENSE.txt for complete terms. diff --git a/plugins/compound-engineering/docs/gemini-imagegen_skill.md b/plugins/compound-engineering/docs/gemini-imagegen_skill.md new file mode 100644 index 0000000..51767c2 --- /dev/null +++ b/plugins/compound-engineering/docs/gemini-imagegen_skill.md @@ -0,0 +1,113 @@ +# Gemini Image Generation Skill + +Generate and edit images using Google's Gemini API with ready-to-use CLI scripts. + +## What This Skill Does + +This skill provides a complete toolkit for AI image generation including: + +- **Text-to-image generation** - Create images from prompts +- **Image editing** - Modify existing images with instructions +- **Multi-image composition** - Combine up to 14 reference images +- **Multi-turn refinement** - Interactive chat-based image iteration +- **Style transfer** - Apply artistic styles to images + +## Common Workflows + +### 1. Generate Product Images +Create studio-quality product photos with specific lighting and composition. + +```bash +python scripts/generate_image.py "Studio-lit product photo on polished concrete" product.jpg +``` + +### 2. Edit Existing Images +Add elements, change backgrounds, or modify existing images. + +```bash +python scripts/edit_image.py input.jpg "Add a sunset background" output.jpg +``` + +### 3. Create Marketing Assets +Generate logos, social media graphics, and brand imagery. + +```bash +python scripts/generate_image.py "Logo with text 'Daily Grind' in clean sans-serif" logo.jpg +``` + +### 4. Combine Reference Images +Merge multiple images into a cohesive composition. + +```bash +python scripts/compose_images.py "Combine these into a collage" out.jpg img1.jpg img2.jpg +``` + +### 5. Interactive Refinement Session +Iteratively refine an image through conversation. + +```bash +python scripts/multi_turn_chat.py +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install gemini-imagegen --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install gemini-imagegen --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install gemini-imagegen --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install gemini-imagegen --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## Requirements + +- Python 3.8+ +- `GEMINI_API_KEY` environment variable +- Dependencies from `requirements.txt` + +## License + +MIT diff --git a/plugins/compound-engineering/docs/git-worktree_skill.md b/plugins/compound-engineering/docs/git-worktree_skill.md new file mode 100644 index 0000000..8e90600 --- /dev/null +++ b/plugins/compound-engineering/docs/git-worktree_skill.md @@ -0,0 +1,118 @@ +# Git Worktree Manager Skill + +Manage Git worktrees for isolated parallel development, code review workflows, and safe feature development. + +## What This Skill Does + +This skill provides a complete toolkit for Git worktree management: + +- **Parallel development** - Work on multiple features simultaneously in isolated directories +- **Code review isolation** - Review PRs without switching branches or losing work +- **Branch safety** - Create, switch, and cleanup worktrees with proper env file handling +- **Automatic setup** - Copies .env files and manages .gitignore entries +- **Workflow integration** - Works with /workflows:review and /workflows:work commands + +## Common Workflows + +### 1. Isolated PR Review +Create a worktree for reviewing a PR without affecting current work. + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name +cd .worktrees/pr-123-feature-name +# Review code, run tests +cd ../.. +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup +``` + +### 2. Parallel Feature Development +Work on two features simultaneously without branch switching. + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-dashboard +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list +``` + +### 3. Switch Between Worktrees +Navigate between active worktrees. + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login +``` + +### 4. Copy Environment Files +Ensure a worktree has all necessary env files. + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login +``` + +### 5. Cleanup After Completion +Remove completed worktrees and clean up. + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install git-worktree --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install git-worktree --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install git-worktree --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install git-worktree --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## Requirements + +- Git 2.5+ (worktree support) +- Bash shell + +## License + +MIT diff --git a/plugins/compound-engineering/docs/rclone_skill.md b/plugins/compound-engineering/docs/rclone_skill.md new file mode 100644 index 0000000..99cee68 --- /dev/null +++ b/plugins/compound-engineering/docs/rclone_skill.md @@ -0,0 +1,112 @@ +# rclone File Transfer Skill + +Transfer files to cloud storage using rclone with support for S3, Cloudflare R2, Backblaze B2, Google Drive, Dropbox, and 40+ cloud providers. + +## What This Skill Does + +This skill provides a streamlined workflow for transferring files to cloud storage: + +- **Provider configuration** - Set up remotes for any cloud storage +- **File uploads** - Single files or entire directories +- **Sync operations** - Mirror local folders to cloud with deletes +- **Transfer verification** - Confirm uploads with integrity checks +- **Troubleshooting** - Debug and fix common issues + +## Common Workflows + +### 1. Upload Files to S3/R2/B2 +Transfer files to S3-compatible storage with progress tracking. + +```bash +rclone copy video.mp4 r2:my-bucket/videos/ --progress +``` + +### 2. Sync a Directory to Cloud +Mirror a local folder to cloud storage (includes deletions). + +```bash +rclone sync ./local-folder remote:bucket/folder/ --progress +``` + +### 3. Verify Transfer Integrity +Confirm files were uploaded correctly. + +```bash +rclone check /local/file remote:bucket/file +``` + +### 4. Configure New Cloud Provider +Set up a new remote for any supported provider. + +```bash +rclone config +``` + +### 5. Backup with Large Files +Handle large file uploads with appropriate chunk sizes. + +```bash +rclone copy big-video.mp4 remote:bucket/ --s3-chunk-size=64M --progress +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install rclone --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install rclone --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install rclone --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install rclone --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## Requirements + +- rclone installed (`brew install rclone` or `curl https://rclone.org/install.sh | sudo bash`) +- Configured remote (`rclone config`) + +## License + +MIT diff --git a/plugins/compound-engineering/docs/skill-creator_skill.md b/plugins/compound-engineering/docs/skill-creator_skill.md new file mode 100644 index 0000000..9b3d59f --- /dev/null +++ b/plugins/compound-engineering/docs/skill-creator_skill.md @@ -0,0 +1,112 @@ +# Skill Creator Skill + +Create and update Claude Code Skills with specialized knowledge, workflows, and tool integrations following best practices. + +## What This Skill Does + +This skill guides the creation of effective Claude Code Skills: + +- **Template generation** - Initialize skills with proper structure +- **YAML frontmatter** - Ensure correct metadata format +- **Progressive disclosure** - Organize content efficiently +- **Bundled resources** - Add scripts, references, and assets +- **Validation** - Check skills against the specification +- **Packaging** - Prepare skills for distribution + +## Common Workflows + +### 1. Initialize a New Skill +Create a skill template with proper structure. + +```bash +scripts/init_skill.py my-new-skill --path ./skills/ +``` + +### 2. Plan Skill Contents +Gather examples before writing. + +```markdown +# Ask: +# - "What functionality should this skill support?" +# - "What would a user say that should trigger this skill?" +# - "Can you give examples of how this skill would be used?" +``` + +### 3. Add Reference Documentation +Move detailed content to references for token efficiency. + +```markdown +# In SKILL.md, link to references: +See [detailed-guide.md](./references/detailed-guide.md) for full documentation. +``` + +### 4. Validate Skill Structure +Check a skill against the specification. + +```bash +scripts/quick_validate.py ./skills/my-skill/ +``` + +### 5. Package for Distribution +Prepare a skill for sharing. + +```bash +scripts/package_skill.py ./skills/my-skill/ ./dist/ +``` + +## Agent Skill Standard + +This skill follows the [Agent Skill Standard](https://agentskills.io/), an open standard for portable AI coding agent skills. This means it works across 14+ AI coding agents including: + +- Claude Code +- OpenAI Codex +- OpenCode +- Cursor +- Gemini CLI +- GitHub Copilot CLI +- Windsurf +- And more... + +## Installing with Skilz (Universal Installer) + +The recommended way to install this skill across different AI coding agents is using the **skilz** universal installer. + +### Install Skilz + +```bash +pip install skilz +``` + +### Installation Options + +#### Option 1: Install for Claude Code + +```bash +skilz install skill-creator --agent claude-code +``` + +#### Option 2: Install for OpenCode + +```bash +skilz install skill-creator --agent opencode +``` + +#### Option 3: Install for Gemini CLI + +```bash +skilz install skill-creator --agent gemini +``` + +#### Option 4: Install for OpenAI Codex + +```bash +skilz install skill-creator --agent codex +``` + +### Install from SkillzWave Marketplace + +Visit [SkillzWave.ai](https://skillzwave.ai) to browse and install skills with one click. + +## License + +Complete terms in LICENSE.txt diff --git a/plugins/compound-engineering/docs/skills.md b/plugins/compound-engineering/docs/skills.md new file mode 100644 index 0000000..9b9d425 --- /dev/null +++ b/plugins/compound-engineering/docs/skills.md @@ -0,0 +1,294 @@ +# Skills Documentation + +This document provides detailed documentation for all 13 skills included in the Compound Engineering Plugin. + +## Quick Reference + +| Skill | Category | Purpose | +|-------|----------|---------| +| [agent-native-architecture](#agent-native-architecture) | Architecture | Build AI agents using prompt-native design | +| [andrew-kane-gem-writer](#andrew-kane-gem-writer) | Ruby | Write gems following Andrew Kane patterns | +| [compound-docs](#compound-docs) | Documentation | Capture solved problems as docs | +| [create-agent-skills](#create-agent-skills) | Development | Create Claude Code skills | +| [dhh-rails-style](#dhh-rails-style) | Ruby/Rails | Write code in DHH's 37signals style | +| [dspy-ruby](#dspy-ruby) | Ruby/AI | Build type-safe LLM applications | +| [every-style-editor](#every-style-editor) | Editing | Review copy for Every's style guide | +| [file-todos](#file-todos) | Workflow | File-based todo tracking | +| [frontend-design](#frontend-design) | Design | Create distinctive frontend interfaces | +| [gemini-imagegen](#gemini-imagegen) | Image | Generate images with Gemini API | +| [git-worktree](#git-worktree) | Git | Manage worktrees for parallel dev | +| [rclone](#rclone) | File Transfer | Upload to S3, R2, B2, cloud storage | +| [skill-creator](#skill-creator) | Development | Guide for creating Claude skills | + +## Installation + +### Claude Code (Native) + +Skills are automatically available when the plugin is installed: + +```bash +claude /plugin install compound-engineering +``` + +### Portable Installation (Other AI Coding Agents) + +Skills follow the [Agent Skills Standard](https://agentskills.io) and can be installed into any compatible AI coding agent. + +#### Manual Installation + +1. Copy the skill folder to your agent's skills directory: + ```bash + # Example for Claude Code + cp -r skills/skill-name ~/.claude/skills/ + + # Example for Cursor + cp -r skills/skill-name ~/.cursor/skills/ + + # Example for Windsurf + cp -r skills/skill-name ~/.windsurf/skills/ + ``` + +2. Restart your agent to load the skill + +#### From GitHub + +```bash +# Clone the repo +git clone https://github.com/EveryInc/compound-engineering-plugin.git + +# Copy desired skills +cp -r compound-engineering-plugin/plugins/compound-engineering/skills/skill-name ~/.claude/skills/ +``` + +## Skill Details + +### agent-native-architecture + +Build AI agents using prompt-native architecture principles. + +**Triggers:** "agent-native", "prompt architecture", "action context parity", "agentic design patterns", "build AI agent" + +**Key Features:** +- Pattern library for agentic architectures +- Action/context parity validation +- Tool use optimization strategies + +[Full documentation](./agent-native-architecture_skill.md) + +--- + +### andrew-kane-gem-writer + +Write Ruby gems following Andrew Kane's battle-tested patterns from 100+ gems. + +**Triggers:** "create a gem", "write a Ruby library", "Andrew Kane style", "gem API design", "minimal gem", "Searchkick patterns" + +**Key Features:** +- Zero-dependency gem architecture +- Rails integration patterns with ActiveSupport.on_load +- Class macro DSL patterns +- Minitest-based testing + +[Full documentation](./andrew-kane-gem-writer_skill.md) + +--- + +### compound-docs + +Capture solved problems as categorized documentation that compounds team knowledge. + +**Triggers:** "document solution", "create solution doc", "compound knowledge", "capture fix", "record how we solved" + +**Key Features:** +- Categorized solution templates +- Problem/solution/prevention format +- Knowledge compounding over time + +[Full documentation](./compound-docs_skill.md) + +--- + +### create-agent-skills + +Expert guidance for creating Claude Code skills following official specifications. + +**Triggers:** "create skill", "write skill", "SKILL.md", "skill best practices", "author skill" + +**Key Features:** +- Skill structure templates +- Progressive disclosure patterns +- Quality checklists + +[Full documentation](./create-agent-skills_skill.md) + +--- + +### dhh-rails-style + +Write Ruby/Rails code in DHH's 37signals style with strong opinions on structure. + +**Triggers:** "DHH style", "37signals Rails", "Rails conventions", "Basecamp patterns", "Hotwire implementation" + +**Key Features:** +- Controller patterns (thin controllers, fat models) +- Hotwire/Turbo integration +- Convention over configuration + +[Full documentation](./dhh-rails-style_skill.md) + +--- + +### dspy-ruby + +Build type-safe LLM applications with DSPy.rb framework. + +**Triggers:** "DSPy", "DSPy.rb", "LLM in Ruby", "Ruby AI", "type-safe LLM", "Ruby language model" + +**Key Features:** +- Type-safe signatures for LLM operations +- Composable modules and workflows +- Multi-provider support (OpenAI, Anthropic, Gemini, Ollama) +- Multimodal/vision capabilities + +[Full documentation](./dspy-ruby_skill.md) + +--- + +### every-style-editor + +Review and edit copy to ensure adherence to Every's comprehensive style guide. + +**Triggers:** "edit for style", "review article", "check grammar", "Every style guide", "proofread", "copy edit" + +**Key Features:** +- 4-phase review process +- Detailed line edit checklists +- Style guide quick reference tables + +[Full documentation](./every-style-editor_skill.md) + +--- + +### file-todos + +File-based todo tracking system for managing tasks across projects. + +**Triggers:** "track todos", "file-based tasks", "todo list", "task tracking" + +**Key Features:** +- Persistent file-based storage +- Status tracking (pending, in_progress, completed) +- Integration with development workflow + +[Full documentation](./file-todos_skill.md) + +--- + +### frontend-design + +Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. + +**Triggers:** "build a landing page", "create a component", "design a UI", "make a web page", "build frontend", "React component", "Vue component" + +**Key Features:** +- 3-phase design workflow +- Aesthetic direction system (8 distinct directions) +- Production-grade component patterns + +[Full documentation](./frontend-design_skill.md) + +--- + +### gemini-imagegen + +Generate and edit images using Google's Gemini API with multi-turn refinement. + +**Triggers:** "generate image", "create picture", "Gemini image", "AI image generation", "imagen", "gemini-imagegen" + +**Key Features:** +- Text-to-image generation +- Image editing and manipulation +- Multi-turn refinement workflows +- Multiple reference image composition (up to 14 images) + +**Requirements:** +- `GEMINI_API_KEY` environment variable +- Python packages: `google-genai`, `pillow` + +[Full documentation](./gemini-imagegen_skill.md) + +--- + +### git-worktree + +Manage Git worktrees for parallel development across multiple features. + +**Triggers:** "git worktree", "parallel branches", "multiple features", "worktree setup" + +**Key Features:** +- Worktree lifecycle management +- Parallel development patterns +- Branch isolation strategies + +[Full documentation](./git-worktree_skill.md) + +--- + +### rclone + +Upload files to S3, Cloudflare R2, Backblaze B2, and other cloud storage providers. + +**Triggers:** "upload to S3", "cloud storage", "rclone sync", "backup files", "R2 upload", "B2 backup" + +**Key Features:** +- Multi-provider support (S3, R2, B2, GDrive, Dropbox) +- Sync and copy operations +- Transfer verification + +[Full documentation](./rclone_skill.md) + +--- + +### skill-creator + +Comprehensive guide for creating effective Claude Code skills with bundled resources. + +**Triggers:** "create a skill", "new skill", "write a skill", "update skill", "skill template" + +**Key Features:** +- 6-step creation process +- Bundled resources guide (scripts, references, assets) +- Packaging and validation scripts + +[Full documentation](./skill-creator_skill.md) + +--- + +## Skill Compatibility + +All skills in this plugin follow the [Agent Skills Standard](https://agentskills.io) and are compatible with: + +| Agent | Skill Directory | Status | +|-------|-----------------|--------| +| Claude Code | `~/.claude/skills/` | Tested | +| Cursor | `~/.cursor/skills/` | Compatible | +| Windsurf | `~/.windsurf/skills/` | Compatible | +| Continue | `~/.continue/skills/` | Compatible | +| Aider | `~/.aider/skills/` | Compatible | +| Cline | `~/.cline/skills/` | Compatible | +| OpenCode | `~/.opencode/skills/` | Compatible | +| Codex CLI | `~/.codex/skills/` | Compatible | + +## Contributing + +To contribute a new skill: + +1. Use the `create-agent-skills` or `skill-creator` skill for guidance +2. Follow the YAML frontmatter specification +3. Include trigger keywords in the description +4. Add quality checklist if applicable +5. Submit a PR with documentation + +## License + +MIT diff --git a/plugins/compound-engineering/skills/agent-native-architecture/SKILL.md b/plugins/compound-engineering/skills/agent-native-architecture/SKILL.md index 10d5a23..d600b0e 100644 --- a/plugins/compound-engineering/skills/agent-native-architecture/SKILL.md +++ b/plugins/compound-engineering/skills/agent-native-architecture/SKILL.md @@ -1,8 +1,30 @@ --- name: agent-native-architecture description: This skill should be used when building AI agents using prompt-native architecture where features are defined in prompts, not code. Use it when creating autonomous agents, designing MCP servers, implementing self-modifying systems, or adopting the "trust the agent's intelligence" philosophy. +license: MIT +allowed-tools: + - Read + - Write + - Edit + - WebFetch +metadata: + version: "1.1.0" + category: architecture + tags: [agents, mcp, prompt-native, ai-architecture, self-modification] --- +# Agent-Native Architecture + +## Contents + +- [The Prompt-Native Philosophy](#the-prompt-native-philosophy) +- [Intake Menu](#intake-menu) +- [Architecture Review Checklist](#architecture-review-checklist) +- [Quick Start](#quick-start) +- [References](#references) +- [What NOT to Do](#what-not-to-do) +- [Success Criteria](#success-criteria) + ## The Prompt-Native Philosophy @@ -189,7 +211,7 @@ All references in `references/`: **THE CARDINAL SIN: Agent executes your code instead of figuring things out** -This is the most common mistake. You fall back into writing workflow code and having the agent call it, instead of defining outcomes and letting the agent figure out HOW. +This is the most common mistake. The pattern is falling back into writing workflow code and having the agent call it, instead of defining outcomes and letting the agent figure out HOW. ```typescript // WRONG - You wrote the workflow, agent just executes it diff --git a/plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md b/plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md index a874108..bbfebe5 100644 --- a/plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md +++ b/plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md @@ -1,17 +1,39 @@ --- name: andrew-kane-gem-writer -description: This skill should be used when writing Ruby gems following Andrew Kane's proven patterns and philosophy. It applies when creating new Ruby gems, refactoring existing gems, designing gem APIs, or when clean, minimal, production-ready Ruby library code is needed. Triggers on requests like "create a gem", "write a Ruby library", "design a gem API", or mentions of Andrew Kane's style. +description: This skill should be used when writing Ruby gems following Andrew Kane's patterns. Triggers on "create a gem", "write a Ruby library", "Andrew Kane style", "gem API design", "minimal gem", "Searchkick patterns", or requests for clean, dependency-free, production-ready Ruby library code. +license: MIT +allowed-tools: + - Read + - Write + - Edit + - Bash +metadata: + version: "1.1.0" + category: ruby + tags: [ruby, gems, libraries, andrew-kane, rails] --- # Andrew Kane Gem Writer +## Contents + +- [Overview](#overview) +- [Core Philosophy](#core-philosophy) +- [Key Patterns](#key-patterns) +- [Anti-Patterns](#anti-patterns-to-avoid) +- [References](#reference-files) + +## Overview + Write Ruby gems following Andrew Kane's battle-tested patterns from 100+ gems with 374M+ downloads (Searchkick, PgHero, Chartkick, Strong Migrations, Lockbox, Ahoy, Blazer, Groupdate, Neighbor, Blind Index). ## Core Philosophy **Simplicity over cleverness.** Zero or minimal dependencies. Explicit code over metaprogramming. Rails integration without Rails coupling. Every pattern serves production use cases. -## Entry Point Structure +## Key Patterns + +### Entry Point Structure Every gem follows this exact pattern in `lib/gemname.rb`: @@ -40,7 +62,7 @@ module GemName end ``` -## Class Macro DSL Pattern +### Class Macro DSL Pattern The signature Kane pattern—single method call configures everything: @@ -74,7 +96,7 @@ module GemName end ``` -## Rails Integration +### Rails Integration **Always use `ActiveSupport.on_load`—never require Rails gems directly:** @@ -94,7 +116,7 @@ ActiveSupport.on_load(:active_record) do end ``` -## Configuration Pattern +### Configuration Pattern Use `class << self` with `attr_accessor`, not Configuration objects: @@ -114,7 +136,7 @@ module GemName end ``` -## Error Handling +### Error Handling Simple hierarchy with informative messages: @@ -131,7 +153,7 @@ def initialize(key:) end ``` -## Testing (Minitest Only) +### Testing (Minitest Only) ```ruby # test/test_helper.rb @@ -148,7 +170,7 @@ class ModelTest < Minitest::Test end ``` -## Gemspec Pattern +### Gemspec Pattern Zero runtime dependencies when possible: @@ -174,6 +196,18 @@ end - RSpec (use Minitest) - Heavy DSLs (prefer explicit Ruby) +## Quality Checklist + +Before publishing a gem: + +- [ ] Entry point follows Kane's exact pattern +- [ ] Zero or minimal runtime dependencies +- [ ] Rails integration uses `ActiveSupport.on_load` +- [ ] Configuration uses `class << self` accessors +- [ ] Error classes defined with clear hierarchy +- [ ] Tests use Minitest (not RSpec) +- [ ] Gemfile.lock NOT committed + ## Reference Files For deeper patterns, see: diff --git a/plugins/compound-engineering/skills/compound-docs/SKILL.md b/plugins/compound-engineering/skills/compound-docs/SKILL.md index 678a594..cdddc4d 100644 --- a/plugins/compound-engineering/skills/compound-docs/SKILL.md +++ b/plugins/compound-engineering/skills/compound-docs/SKILL.md @@ -1,11 +1,16 @@ --- name: compound-docs -description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup +description: This skill should be used when documenting solved problems as categorized documentation with YAML frontmatter for fast lookup. Use after confirming a fix works, when hearing phrases like "that worked" or "it's fixed", or when running /doc-fix command. +license: MIT allowed-tools: - - Read # Parse conversation context - - Write # Create resolution docs - - Bash # Create directories - - Grep # Search existing docs + - Read + - Write + - Bash + - Grep +metadata: + version: "1.1.0" + category: documentation + tags: [knowledge-base, solutions, documentation, patterns] preconditions: - Problem has been solved (not in-progress) - Solution has been verified working @@ -13,498 +18,125 @@ preconditions: # compound-docs Skill -**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types). +## Contents + +- [Overview](#overview) +- [Quick Start](#quick-start) +- [7-Step Process Summary](#7-step-process-summary) +- [File Organization](#file-organization) +- [Integration Points](#integration-points) +- [References](#references) ## Overview This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions. -**Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability. - ---- - - - -## 7-Step Process - - -### Step 1: Detect Confirmation +**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types). -**Auto-invoke after phrases:** +**Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). -- "that worked" -- "it's fixed" -- "working now" -- "problem solved" -- "that did it" +## Quick Start -**OR manual:** `/doc-fix` command +**Trigger phrases:** "that worked", "it's fixed", "working now", "problem solved" -**Non-trivial problems only:** +**Manual command:** `/doc-fix` +**Document when:** - Multiple investigation attempts needed - Tricky debugging that took time - Non-obvious solution - Future sessions would benefit -**Skip documentation for:** - -- Simple typos -- Obvious syntax errors -- Trivial fixes immediately corrected - - - -### Step 2: Gather Context - -Extract from conversation history: - -**Required information:** - -- **Module name**: Which CORA module had the problem -- **Symptom**: Observable error/behavior (exact error messages) -- **Investigation attempts**: What didn't work and why -- **Root cause**: Technical explanation of actual problem -- **Solution**: What fixed it (code/config changes) -- **Prevention**: How to avoid in future - -**Environment details:** - -- Rails version -- Stage (0-6 or post-implementation) -- OS version -- File/line references - -**BLOCKING REQUIREMENT:** If critical context is missing (module name, exact error, stage, or resolution steps), ask user and WAIT for response before proceeding to Step 3: - -``` -I need a few details to document this properly: - -1. Which module had this issue? [ModuleName] -2. What was the exact error message or symptom? -3. What stage were you in? (0-6 or post-implementation) - -[Continue after user provides details] -``` - - - -### Step 3: Check Existing Docs - -Search docs/solutions/ for similar issues: - -```bash -# Search by error message keywords -grep -r "exact error phrase" docs/solutions/ - -# Search by symptom category -ls docs/solutions/[category]/ -``` - -**IF similar issue found:** - -THEN present decision options: - -``` -Found similar issue: docs/solutions/[path] - -What's next? -1. Create new doc with cross-reference (recommended) -2. Update existing doc (only if same root cause) -3. Other - -Choose (1-3): _ -``` - -WAIT for user response, then execute chosen action. - -**ELSE** (no similar issue found): +**Skip for:** Simple typos, obvious syntax errors, trivial fixes -Proceed directly to Step 4 (no user interaction needed). - +## 7-Step Process Summary - -### Step 4: Generate Filename +| Step | Action | Blocking? | +|------|--------|-----------| +| 1. Detect | Auto-invoke on confirmation phrases | No | +| 2. Gather | Extract context from conversation | Yes (if missing info) | +| 3. Check | Search for similar existing docs | No | +| 4. Filename | Generate sanitized filename | No | +| 5. Validate | Validate YAML against schema | Yes (blocks until valid) | +| 6. Create | Write documentation file | No | +| 7. Cross-ref | Link related issues, detect patterns | No | -Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md` +**Full process details:** See [7-step-process.md](./references/7-step-process.md) -**Sanitization rules:** +## File Organization -- Lowercase -- Replace spaces with hyphens -- Remove special characters except hyphens -- Truncate to reasonable length (< 80 chars) - -**Examples:** - -- `missing-include-BriefSystem-20251110.md` -- `parameter-not-saving-state-EmailProcessing-20251110.md` -- `webview-crash-on-resize-Assistant-20251110.md` - - - -### Step 5: Validate YAML Schema - -**CRITICAL:** All docs require validated YAML frontmatter with enum validation. - - - -**Validate against schema:** -Load `schema.yaml` and classify the problem against the enum values defined in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly. - -**BLOCK if validation fails:** - -``` -❌ YAML validation failed - -Errors: -- problem_type: must be one of schema enums, got "compilation_error" -- severity: must be one of [critical, moderate, minor], got "high" -- symptoms: must be array with 1-5 items, got string - -Please provide corrected values. -``` - -**GATE ENFORCEMENT:** Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in `schema.yaml`. - - - - - -### Step 6: Create Documentation - -**Determine category from problem_type:** Use the category mapping defined in [yaml-schema.md](./references/yaml-schema.md) (lines 49-61). - -**Create documentation file:** - -```bash -PROBLEM_TYPE="[from validated YAML]" -CATEGORY="[mapped from problem_type]" -FILENAME="[generated-filename].md" -DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}" - -# Create directory if needed -mkdir -p "docs/solutions/${CATEGORY}" - -# Write documentation using template from assets/resolution-template.md -# (Content populated with Step 2 context and validated YAML frontmatter) +**Directory structure:** ``` - -**Result:** -- Single file in category directory -- Enum validation ensures consistent categorization - -**Create documentation:** Populate the structure from `assets/resolution-template.md` with context gathered in Step 2 and validated YAML frontmatter from Step 5. - - - -### Step 7: Cross-Reference & Critical Pattern Detection - -If similar issues found in Step 3: - -**Update existing doc:** - -```bash -# Add Related Issues link to similar doc -echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md] +docs/solutions/ +├── performance-issues/ # problem_type: performance_issue +├── configuration-errors/ # problem_type: configuration_error +├── integration-problems/ # problem_type: integration_problem +├── type-errors/ # problem_type: type_error +└── patterns/ # Cross-cutting patterns + └── common-solutions.md ``` -**Update new doc:** -Already includes cross-reference from Step 6. - -**Update patterns if applicable:** +**Filename format:** `[sanitized-symptom]-[module]-[YYYYMMDD].md` -If this represents a common pattern (3+ similar issues): +**Category mapping:** See [yaml-schema.md](./references/yaml-schema.md) for problem_type → category mapping. -```bash -# Add to docs/solutions/patterns/common-solutions.md -cat >> docs/solutions/patterns/common-solutions.md << 'EOF' +## YAML Validation (CRITICAL) -## [Pattern Name] +All documentation requires validated YAML frontmatter. **BLOCK until valid.** -**Common symptom:** [Description] -**Root cause:** [Technical explanation] -**Solution pattern:** [General approach] +Required fields from [schema.yaml](./schema.yaml): +- `module`, `date`, `problem_type`, `component` +- `symptoms` (array 1-5 items) +- `root_cause`, `severity`, `tags` -**Examples:** -- [Link to doc 1] -- [Link to doc 2] -- [Link to doc 3] -EOF -``` +Validation errors must be shown and corrected before proceeding. -**Critical Pattern Detection (Optional Proactive Suggestion):** +## Decision Menu -If this issue has automatic indicators suggesting it might be critical: -- Severity: `critical` in YAML -- Affects multiple modules OR foundational stage (Stage 2 or 3) -- Non-obvious solution - -Then in the decision menu (Step 8), add a note: -``` -💡 This might be worth adding to Required Reading (Option 2) -``` - -But **NEVER auto-promote**. User decides via decision menu (Option 2). - -**Template for critical pattern addition:** - -When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/cora-critical-patterns.md`. - - - - ---- - - - -## Decision Menu After Capture - -After successful documentation, present options and WAIT for user response: +After successful documentation, present: ``` ✓ Solution documented -File created: -- docs/solutions/[category]/[filename].md - What's next? 1. Continue workflow (recommended) -2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md) -3. Link related issues - Connect to similar problems -4. Add to existing skill - Add to a learning skill (e.g., hotwire-native) -5. Create new skill - Extract into new learning skill -6. View documentation - See what was captured +2. Add to Required Reading +3. Link related issues +4. Add to existing skill +5. Create new skill +6. View documentation 7. Other ``` -**Handle responses:** - -**Option 1: Continue workflow** - -- Return to calling skill/workflow -- Documentation is complete - -**Option 2: Add to Required Reading** ⭐ PRIMARY PATH FOR CRITICAL PATTERNS - -User selects this when: -- System made this mistake multiple times across different modules -- Solution is non-obvious but must be followed every time -- Foundational requirement (Rails, Rails API, threading, etc.) - -Action: -1. Extract pattern from the documentation -2. Format as ❌ WRONG vs ✅ CORRECT with code examples -3. Add to `docs/solutions/patterns/cora-critical-patterns.md` -4. Add cross-reference back to this doc -5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation." - -**Option 3: Link related issues** - -- Prompt: "Which doc to link? (provide filename or describe)" -- Search docs/solutions/ for the doc -- Add cross-reference to both docs -- Confirm: "✓ Cross-reference added" - -**Option 4: Add to existing skill** - -User selects this when the documented solution relates to an existing learning skill: - -Action: -1. Prompt: "Which skill? (hotwire-native, etc.)" -2. Determine which reference file to update (resources.md, patterns.md, or examples.md) -3. Add link and brief description to appropriate section -4. Confirm: "✓ Added to [skill-name] skill in [file]" - -Example: For Hotwire Native Tailwind variants solution: -- Add to `hotwire-native/references/resources.md` under "CORA-Specific Resources" -- Add to `hotwire-native/references/examples.md` with link to solution doc - -**Option 5: Create new skill** - -User selects this when the solution represents the start of a new learning domain: - -Action: -1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)" -2. Run `python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]` -3. Create initial reference files with this solution as first example -4. Confirm: "✓ Created new [skill-name] skill with this solution as first example" - -**Option 6: View documentation** - -- Display the created documentation -- Present decision menu again - -**Option 7: Other** - -- Ask what they'd like to do - - - ---- - - +**Full menu details:** See [decision-menu.md](./references/decision-menu.md) ## Integration Points **Invoked by:** -- /compound command (primary interface) -- Manual invocation in conversation after solution confirmed -- Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc. - -**Invokes:** -- None (terminal skill - does not delegate to other skills) - -**Handoff expectations:** -All context needed for documentation should be present in conversation history before invocation. +- `/compound` command (primary interface) +- Manual invocation after solution confirmed +- Auto-triggered by confirmation phrases - - ---- +**Invokes:** None (terminal skill) - +**Handoff:** All context needed should be present in conversation history. -## Success Criteria +## References -Documentation is successful when ALL of the following are true: - -- ✅ YAML frontmatter validated (all required fields, correct formats) -- ✅ File created in docs/solutions/[category]/[filename].md -- ✅ Enum values match schema.yaml exactly -- ✅ Code examples included in solution section -- ✅ Cross-references added if related issues found -- ✅ User presented with decision menu and action confirmed - - - ---- - -## Error Handling - -**Missing context:** - -- Ask user for missing details -- Don't proceed until critical info provided - -**YAML validation failure:** - -- Show specific errors -- Present retry with corrected values -- BLOCK until valid - -**Similar issue ambiguity:** - -- Present multiple matches -- Let user choose: new doc, update existing, or link as duplicate - -**Module not in CORA-MODULES.md:** - -- Warn but don't block -- Proceed with documentation -- Suggest: "Add [Module] to CORA-MODULES.md if not there" - ---- - -## Execution Guidelines - -**MUST do:** -- Validate YAML frontmatter (BLOCK if invalid per Step 5 validation gate) -- Extract exact error messages from conversation -- Include code examples in solution section -- Create directories before writing files (`mkdir -p`) -- Ask user and WAIT if critical context missing - -**MUST NOT do:** -- Skip YAML validation (validation gate is blocking) -- Use vague descriptions (not searchable) -- Omit code examples or cross-references - ---- - -## Quality Guidelines - -**Good documentation has:** - -- ✅ Exact error messages (copy-paste from output) -- ✅ Specific file:line references -- ✅ Observable symptoms (what you saw, not interpretations) -- ✅ Failed attempts documented (helps avoid wrong paths) -- ✅ Technical explanation (not just "what" but "why") -- ✅ Code examples (before/after if applicable) -- ✅ Prevention guidance (how to catch early) -- ✅ Cross-references (related issues) - -**Avoid:** - -- ❌ Vague descriptions ("something was wrong") -- ❌ Missing technical details ("fixed the code") -- ❌ No context (which version? which file?) -- ❌ Just code dumps (explain why it works) -- ❌ No prevention guidance -- ❌ No cross-references - ---- - -## Example Scenario - -**User:** "That worked! The N+1 query is fixed." - -**Skill activates:** - -1. **Detect confirmation:** "That worked!" triggers auto-invoke -2. **Gather context:** - - Module: Brief System - - Symptom: Brief generation taking >5 seconds, N+1 query when loading email threads - - Failed attempts: Added pagination (didn't help), checked background job performance - - Solution: Added eager loading with `includes(:emails)` on Brief model - - Root cause: Missing eager loading causing separate database query per email thread -3. **Check existing:** No similar issue found -4. **Generate filename:** `n-plus-one-brief-generation-BriefSystem-20251110.md` -5. **Validate YAML:** - ```yaml - module: Brief System - date: 2025-11-10 - problem_type: performance_issue - component: rails_model - symptoms: - - "N+1 query when loading email threads" - - "Brief generation taking >5 seconds" - root_cause: missing_include - severity: high - tags: [n-plus-one, eager-loading, performance] - ``` - ✅ Valid -6. **Create documentation:** - - `docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md` -7. **Cross-reference:** None needed (no similar issues) - -**Output:** - -``` -✓ Solution documented - -File created: -- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md - -What's next? -1. Continue workflow (recommended) -2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md) -3. Link related issues - Connect to similar problems -4. Add to existing skill - Add to a learning skill (e.g., hotwire-native) -5. Create new skill - Extract into new learning skill -6. View documentation - See what was captured -7. Other -``` - ---- +### Reference Documentation -## Future Enhancements +| File | Purpose | +|------|---------| +| [7-step-process.md](./references/7-step-process.md) | Detailed step-by-step documentation process | +| [yaml-schema.md](./references/yaml-schema.md) | YAML frontmatter schema and category mapping | +| [decision-menu.md](./references/decision-menu.md) | Post-documentation options and handlers | +| [guidelines.md](./references/guidelines.md) | Error handling, quality checklist, success criteria | +| [example-scenario.md](./references/example-scenario.md) | Complete worked example | -**Not in Phase 7 scope, but potential:** +### Assets (Templates) -- Search by date range -- Filter by severity -- Tag-based search interface -- Metrics (most common issues, resolution time) -- Export to shareable format (community knowledge sharing) -- Import community solutions +| File | Purpose | +|------|---------| +| [resolution-template.md](./assets/resolution-template.md) | Template for documentation files | +| [critical-pattern-template.md](./assets/critical-pattern-template.md) | Template for Required Reading entries | +| [schema.yaml](./schema.yaml) | YAML validation schema | diff --git a/plugins/compound-engineering/skills/compound-docs/references/7-step-process.md b/plugins/compound-engineering/skills/compound-docs/references/7-step-process.md new file mode 100644 index 0000000..7025f40 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-docs/references/7-step-process.md @@ -0,0 +1,109 @@ +# 7-Step Documentation Process + +## Step 1: Detect Confirmation + +**Auto-invoke after phrases:** +- "that worked" +- "it's fixed" +- "working now" +- "problem solved" +- "that did it" + +**OR manual:** `/doc-fix` command + +**Document when:** +- Multiple investigation attempts needed +- Tricky debugging that took time +- Non-obvious solution +- Future sessions would benefit + +**Skip for:** Simple typos, obvious syntax errors, trivial fixes + +## Step 2: Gather Context + +Extract from conversation history: + +**Required information:** +- **Module name**: Which module had the problem +- **Symptom**: Observable error/behavior (exact error messages) +- **Investigation attempts**: What didn't work and why +- **Root cause**: Technical explanation of actual problem +- **Solution**: What fixed it (code/config changes) +- **Prevention**: How to avoid in future + +**Environment details:** Rails version, Stage (0-6), OS version, file/line references + +**BLOCKING:** If critical context missing, ask user and WAIT: +``` +I need a few details to document this properly: + +1. Which module had this issue? [ModuleName] +2. What was the exact error message or symptom? +3. What stage were you in? (0-6 or post-implementation) +``` + +## Step 3: Check Existing Docs + +Search docs/solutions/ for similar issues: + +```bash +grep -r "exact error phrase" docs/solutions/ +ls docs/solutions/[category]/ +``` + +**IF similar found:** Present options (new doc, update existing, link as duplicate) + +**ELSE:** Proceed to Step 4 + +## Step 4: Generate Filename + +Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md` + +**Sanitization:** +- Lowercase +- Replace spaces with hyphens +- Remove special characters except hyphens +- Truncate to < 80 chars + +**Examples:** +- `missing-include-BriefSystem-20251110.md` +- `parameter-not-saving-state-EmailProcessing-20251110.md` + +## Step 5: Validate YAML Schema + +**CRITICAL:** Validate against [yaml-schema.md](./yaml-schema.md) before proceeding. + +**BLOCK if validation fails:** +``` +❌ YAML validation failed + +Errors: +- problem_type: must be one of schema enums +- severity: must be one of [critical, moderate, minor] + +Please provide corrected values. +``` + +Do NOT proceed to Step 6 until YAML passes validation. + +## Step 6: Create Documentation + +1. Determine category from problem_type (see [yaml-schema.md](./yaml-schema.md)) +2. Create directory: `mkdir -p "docs/solutions/${CATEGORY}"` +3. Write file using [resolution-template.md](../assets/resolution-template.md) + +## Step 7: Cross-Reference & Pattern Detection + +**If similar issues found:** +- Add cross-references to both docs +- Update new doc with related links + +**If 3+ similar issues exist:** +- Add to `docs/solutions/patterns/common-solutions.md` + +**Critical pattern indicators:** +- Severity: `critical` +- Affects multiple modules OR foundational stage +- Non-obvious solution + +Suggest adding to Required Reading but NEVER auto-promote. diff --git a/plugins/compound-engineering/skills/compound-docs/references/decision-menu.md b/plugins/compound-engineering/skills/compound-docs/references/decision-menu.md new file mode 100644 index 0000000..30aa98f --- /dev/null +++ b/plugins/compound-engineering/skills/compound-docs/references/decision-menu.md @@ -0,0 +1,65 @@ +# Decision Menu After Documentation + +After successful documentation, present options and WAIT for user response: + +``` +✓ Solution documented + +File created: +- docs/solutions/[category]/[filename].md + +What's next? +1. Continue workflow (recommended) +2. Add to Required Reading +3. Link related issues +4. Add to existing skill +5. Create new skill +6. View documentation +7. Other +``` + +## Option Handlers + +### Option 1: Continue Workflow +Return to calling skill/workflow. Documentation is complete. + +### Option 2: Add to Required Reading +Use when: +- System made this mistake multiple times +- Solution is non-obvious but must be followed every time +- Foundational requirement + +Action: +1. Extract pattern from documentation +2. Format as ❌ WRONG vs ✅ CORRECT with code examples +3. Add to `docs/solutions/patterns/cora-critical-patterns.md` +4. Use [critical-pattern-template.md](../assets/critical-pattern-template.md) +5. Confirm: "✓ Added to Required Reading" + +### Option 3: Link Related Issues +1. Prompt: "Which doc to link?" +2. Search docs/solutions/ +3. Add cross-reference to both docs +4. Confirm: "✓ Cross-reference added" + +### Option 4: Add to Existing Skill +Use when solution relates to an existing learning skill. + +1. Prompt: "Which skill?" +2. Determine which reference file to update +3. Add link and brief description +4. Confirm: "✓ Added to [skill-name]" + +### Option 5: Create New Skill +Use when solution represents start of new learning domain. + +1. Prompt: "What should the new skill be called?" +2. Run skill creator script +3. Create initial reference with this solution +4. Confirm: "✓ Created new [skill-name] skill" + +### Option 6: View Documentation +Display created documentation, then show menu again. + +### Option 7: Other +Ask what they'd like to do. diff --git a/plugins/compound-engineering/skills/compound-docs/references/example-scenario.md b/plugins/compound-engineering/skills/compound-docs/references/example-scenario.md new file mode 100644 index 0000000..12db9ec --- /dev/null +++ b/plugins/compound-engineering/skills/compound-docs/references/example-scenario.md @@ -0,0 +1,60 @@ +# Example Scenario + +**User:** "That worked! The N+1 query is fixed." + +## Step-by-Step Execution + +### 1. Detect Confirmation +"That worked!" triggers auto-invoke. + +### 2. Gather Context +- **Module:** Brief System +- **Symptom:** Brief generation taking >5 seconds, N+1 query when loading email threads +- **Failed attempts:** Added pagination (didn't help), checked background job performance +- **Solution:** Added eager loading with `includes(:emails)` on Brief model +- **Root cause:** Missing eager loading causing separate database query per email thread + +### 3. Check Existing +No similar issue found → proceed. + +### 4. Generate Filename +`n-plus-one-brief-generation-BriefSystem-20251110.md` + +### 5. Validate YAML +```yaml +module: Brief System +date: 2025-11-10 +problem_type: performance_issue +component: rails_model +symptoms: + - "N+1 query when loading email threads" + - "Brief generation taking >5 seconds" +root_cause: missing_include +severity: high +tags: [n-plus-one, eager-loading, performance] +``` +✅ Valid + +### 6. Create Documentation +File: `docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md` + +### 7. Cross-Reference +None needed (no similar issues). + +## Output + +``` +✓ Solution documented + +File created: +- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md + +What's next? +1. Continue workflow (recommended) +2. Add to Required Reading +3. Link related issues +4. Add to existing skill +5. Create new skill +6. View documentation +7. Other +``` diff --git a/plugins/compound-engineering/skills/compound-docs/references/guidelines.md b/plugins/compound-engineering/skills/compound-docs/references/guidelines.md new file mode 100644 index 0000000..9a13df5 --- /dev/null +++ b/plugins/compound-engineering/skills/compound-docs/references/guidelines.md @@ -0,0 +1,54 @@ +# Documentation Guidelines + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Missing context | Ask user, don't proceed until provided | +| YAML validation failure | Show errors, retry with corrected values, BLOCK until valid | +| Similar issue ambiguity | Present matches, let user choose | +| Module not in module list | Warn but don't block, suggest adding module | + +## Execution Rules + +**MUST do:** +- Validate YAML frontmatter (BLOCK if invalid) +- Extract exact error messages from conversation +- Include code examples in solution section +- Create directories before writing files (`mkdir -p`) +- Ask user and WAIT if critical context missing + +**MUST NOT do:** +- Skip YAML validation +- Use vague descriptions (not searchable) +- Omit code examples or cross-references + +## Quality Checklist + +**Good documentation has:** +- [ ] Exact error messages (copy-paste from output) +- [ ] Specific file:line references +- [ ] Observable symptoms (what you saw, not interpretations) +- [ ] Failed attempts documented (helps avoid wrong paths) +- [ ] Technical explanation (not just "what" but "why") +- [ ] Code examples (before/after if applicable) +- [ ] Prevention guidance (how to catch early) +- [ ] Cross-references (related issues) + +**Avoid:** +- Vague descriptions ("something was wrong") +- Missing technical details ("fixed the code") +- No context (which version? which file?) +- Just code dumps (explain why it works) +- No prevention guidance +- No cross-references + +## Success Criteria + +Documentation is complete when: +- YAML frontmatter validated (all required fields, correct formats) +- File created in `docs/solutions/[category]/[filename].md` +- Enum values match schema exactly +- Code examples included +- Cross-references added if related issues found +- User presented with decision menu diff --git a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md index fe69023..c5e2b16 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md +++ b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md @@ -1,10 +1,31 @@ --- -name: creating-agent-skills -description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices. +name: create-agent-skills +description: This skill should be used when creating, writing, or refining Claude Code Skills. Triggers on "create skill", "write skill", "SKILL.md", "skill best practices", "author skill", "improve skill", or requests to work with Claude skill files, authoring, or understanding skill structure. +license: MIT +allowed-tools: + - Read + - Write + - Edit +metadata: + version: "1.1.0" + category: development + tags: [skills, claude-code, authoring, best-practices] --- # Creating Agent Skills +## Contents + +- [Core Principles](#core-principles) +- [Skill Structure](#skill-structure) +- [Creating a New Skill](#creating-a-new-skill) +- [Auditing Existing Skills](#auditing-existing-skills) +- [Common Patterns](#common-patterns) +- [Anti-Patterns](#anti-patterns-to-avoid) +- [References](#reference-files) + +## Overview + This skill teaches how to create effective Claude Code Skills following Anthropic's official specification. ## Core Principles @@ -278,10 +299,38 @@ Guide through decision points: ## Reference Files -For detailed guidance, see: +### Core Documentation + +| File | Purpose | +|------|---------| +| [official-spec.md](references/official-spec.md) | Anthropic's official skill specification | +| [best-practices.md](references/best-practices.md) | Skill authoring best practices | +| [core-principles.md](references/core-principles.md) | Foundational skill design principles | + +### Skill Structure + +| File | Purpose | +|------|---------| +| [skill-structure.md](references/skill-structure.md) | YAML frontmatter and markdown body format | +| [recommended-structure.md](references/recommended-structure.md) | Directory layout and file organization | +| [common-patterns.md](references/common-patterns.md) | Template, workflow, and conditional patterns | + +### Writing & Content + +| File | Purpose | +|------|---------| +| [be-clear-and-direct.md](references/be-clear-and-direct.md) | Writing style for effective skills | +| [using-templates.md](references/using-templates.md) | Output templates and consistency | +| [workflows-and-validation.md](references/workflows-and-validation.md) | Multi-step workflows and checklists | + +### Technical Implementation -- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification -- [best-practices.md](references/best-practices.md) - Skill authoring best practices +| File | Purpose | +|------|---------| +| [using-scripts.md](references/using-scripts.md) | Bundled script patterns and error handling | +| [executable-code.md](references/executable-code.md) | Code examples and execution | +| [api-security.md](references/api-security.md) | Security considerations for skills | +| [iteration-and-testing.md](references/iteration-and-testing.md) | Testing and refinement practices | ## Success Criteria @@ -293,6 +342,18 @@ A well-structured skill: - Includes concrete examples with input/output pairs - Has been tested with real usage +## Quality Checklist + +Before publishing a skill: + +- [ ] Valid YAML frontmatter (name + description) +- [ ] Description includes trigger keywords +- [ ] Uses standard markdown headings (not XML tags) +- [ ] SKILL.md under 500 lines +- [ ] References one level deep +- [ ] Examples are concrete, not abstract +- [ ] Tested with real usage + Sources: - [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills) - [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) diff --git a/plugins/compound-engineering/skills/dhh-rails-style/SKILL.md b/plugins/compound-engineering/skills/dhh-rails-style/SKILL.md index d922e82..bf232ab 100644 --- a/plugins/compound-engineering/skills/dhh-rails-style/SKILL.md +++ b/plugins/compound-engineering/skills/dhh-rails-style/SKILL.md @@ -1,13 +1,32 @@ --- name: dhh-rails-style -description: This skill should be used when writing Ruby and Rails code in DHH's distinctive 37signals style. It applies when writing Ruby code, Rails applications, creating models, controllers, or any Ruby file. Triggers on Ruby/Rails code generation, refactoring requests, code review, or when the user mentions DHH, 37signals, Basecamp, HEY, or Campfire style. Embodies REST purity, fat models, thin controllers, Current attributes, Hotwire patterns, and the "clarity over cleverness" philosophy. +description: This skill should be used when writing Ruby and Rails code in DHH's 37signals style. Triggers on "DHH style", "37signals", "Basecamp style", "Rails conventions", "write Rails code", "Ruby code review", or requests for REST-pure controllers, fat models, thin controllers, and vanilla Rails patterns. +license: MIT +allowed-tools: + - Read + - Write + - Edit +metadata: + version: "1.1.0" + category: rails + tags: [ruby, rails, dhh, 37signals, basecamp, conventions] --- - +# DHH Rails Style + +## Contents + +- [Core Philosophy](#core-philosophy) +- [Intake Menu](#intake-menu) +- [Quick Reference](#quick-reference) +- [References](#references) +- [Code Review Checklist](#code-review-checklist) +- [Credits](#credits) + +## Objective + Apply 37signals/DHH Rails conventions to Ruby and Rails code. This skill provides comprehensive domain expertise extracted from analyzing production 37signals codebases (Fizzy/Campfire) and DHH's code review patterns. - - ## Core Philosophy "The best code is the code you don't write. The second best is the code that's obviously correct." @@ -36,9 +55,9 @@ Apply 37signals/DHH Rails conventions to Ruby and Rails code. This skill provide - Fix root causes, not symptoms - Write-time operations over read-time computations - Database constraints over ActiveRecord validations - - +## Intake Menu + What are you working on? 1. **Controllers** - REST mapping, concerns, Turbo responses, API patterns @@ -51,9 +70,8 @@ What are you working on? 8. **General Guidance** - Philosophy and conventions **Specify a number or describe your task.** - - +### Routing | Response | Reference to Read | |----------|-------------------| | 1, "controller" | [controllers.md](./references/controllers.md) | @@ -66,10 +84,10 @@ What are you working on? | 8, general task | Read relevant references based on context | **After reading relevant references, apply patterns to the user's code.** - - -## Naming Conventions +## Quick Reference + +### Naming Conventions **Verbs:** `card.close`, `card.gild`, `board.publish` (not `set_style` methods) @@ -143,10 +161,10 @@ class User < ApplicationRecord end end ``` - - -## Domain Knowledge +## References + +### Domain Knowledge All detailed patterns in `references/`: @@ -158,27 +176,28 @@ All detailed patterns in `references/`: | [architecture.md](./references/architecture.md) | Routing, authentication, jobs, Current attributes, caching, database patterns | | [testing.md](./references/testing.md) | Minitest, fixtures, unit/integration/system tests, testing patterns | | [gems.md](./references/gems.md) | What they use vs avoid, decision framework, Gemfile examples | - - - -Code follows DHH style when: -- Controllers map to CRUD verbs on resources -- Models use concerns for horizontal behavior -- State is tracked via records, not booleans -- No unnecessary service objects or abstractions -- Database-backed solutions preferred over external services -- Tests use Minitest with fixtures -- Turbo/Stimulus for interactivity (no heavy JS frameworks) -- Native CSS with modern features (layers, OKLCH, nesting) -- Authorization logic lives on User model -- Jobs are shallow wrappers calling model methods - - - + +## Code Review Checklist + +Copy this checklist when reviewing code: + +``` +- [ ] Controllers map to CRUD verbs on resources +- [ ] Models use concerns for horizontal behavior +- [ ] State is tracked via records, not booleans +- [ ] No unnecessary service objects or abstractions +- [ ] Database-backed solutions preferred over external services +- [ ] Tests use Minitest with fixtures +- [ ] Turbo/Stimulus for interactivity (no heavy JS frameworks) +- [ ] Native CSS with modern features (layers, OKLCH, nesting) +- [ ] Authorization logic lives on User model +- [ ] Jobs are shallow wrappers calling model methods +``` + +## Credits Based on [The Unofficial 37signals/DHH Rails Style Guide](https://github.com/marckohlbrugge/unofficial-37signals-coding-style-guide) by [Marc Köhlbrugge](https://x.com/marckohlbrugge), generated through deep analysis of 265 pull requests from the Fizzy codebase. **Important Disclaimers:** - LLM-generated guide - may contain inaccuracies - Code examples from Fizzy are licensed under the O'Saasy License - Not affiliated with or endorsed by 37signals - diff --git a/plugins/compound-engineering/skills/dspy-ruby/SKILL.md b/plugins/compound-engineering/skills/dspy-ruby/SKILL.md index 359a642..4c6cd6e 100644 --- a/plugins/compound-engineering/skills/dspy-ruby/SKILL.md +++ b/plugins/compound-engineering/skills/dspy-ruby/SKILL.md @@ -1,15 +1,33 @@ --- name: dspy-ruby -description: This skill should be used when working with DSPy.rb, a Ruby framework for building type-safe, composable LLM applications. Use this when implementing predictable AI features, creating LLM signatures and modules, configuring language model providers (OpenAI, Anthropic, Gemini, Ollama), building agent systems with tools, optimizing prompts, or testing LLM-powered functionality in Ruby applications. +description: This skill should be used when working with DSPy.rb for building type-safe LLM applications in Ruby. Triggers on "DSPy", "DSPy.rb", "LLM in Ruby", "Ruby AI", "type-safe LLM", "Ruby language model", or requests to create signatures, modules, agents, or integrate OpenAI/Anthropic/Gemini/Ollama in Ruby applications. +license: MIT +allowed-tools: + - Bash + - Read + - Write + - Edit +metadata: + version: "1.1.0" + category: ruby + tags: [llm, ai, dspy, type-safe, ruby, agents] --- # DSPy.rb Expert +## Contents + +- [Overview](#overview) +- [Core Capabilities](#core-capabilities) +- [Quick Start Workflow](#quick-start-workflow) +- [Implementation Checklist](#implementation-checklist) +- [References](#references) + ## Overview DSPy.rb is a Ruby framework that enables developers to **program LLMs, not prompt them**. Instead of manually crafting prompts, define application requirements through type-safe, composable modules that can be tested, optimized, and version-controlled like regular code. -This skill provides comprehensive guidance on: +**Capabilities:** - Creating type-safe signatures for LLM operations - Building composable modules and workflows - Configuring multiple LLM providers @@ -25,7 +43,6 @@ Create input/output contracts for LLM operations with runtime type checking. **When to use**: Defining any LLM task, from simple classification to complex analysis. -**Quick reference**: ```ruby class EmailClassificationSignature < DSPy::Signature description "Classify customer support emails" @@ -42,27 +59,14 @@ class EmailClassificationSignature < DSPy::Signature end ``` -**Templates**: See `assets/signature-template.rb` for comprehensive examples including: -- Basic signatures with multiple field types -- Vision signatures for multimodal tasks -- Sentiment analysis signatures -- Code generation signatures - -**Best practices**: -- Always provide clear, specific descriptions -- Use enums for constrained outputs -- Include field descriptions with `desc:` parameter -- Prefer specific types over generic String when possible +**Templates**: See [signature-template.rb](./assets/signature-template.rb) for comprehensive examples including vision signatures, sentiment analysis, and code generation. -**Full documentation**: See `references/core-concepts.md` sections on Signatures and Type Safety. +**Full documentation**: See [core-concepts.md](./references/core-concepts.md) sections on Signatures and Type Safety. ### 2. Composable Modules Build reusable, chainable modules that encapsulate LLM operations. -**When to use**: Implementing any LLM-powered feature, especially complex multi-step workflows. - -**Quick reference**: ```ruby class EmailProcessor < DSPy::Module def initialize @@ -79,79 +83,27 @@ class EmailProcessor < DSPy::Module end ``` -**Templates**: See `assets/module-template.rb` for comprehensive examples including: -- Basic modules with single predictors -- Multi-step pipelines that chain modules -- Modules with conditional logic -- Error handling and retry patterns -- Stateful modules with history -- Caching implementations +**Templates**: See [module-template.rb](./assets/module-template.rb) for multi-step pipelines, conditional logic, error handling, and caching patterns. -**Module composition**: Chain modules together to create complex workflows: -```ruby -class Pipeline < DSPy::Module - def initialize - super - @step1 = Classifier.new - @step2 = Analyzer.new - @step3 = Responder.new - end - - def forward(input) - result1 = @step1.forward(input) - result2 = @step2.forward(result1) - @step3.forward(result2) - end -end -``` - -**Full documentation**: See `references/core-concepts.md` sections on Modules and Module Composition. +**Full documentation**: See [core-concepts.md](./references/core-concepts.md) sections on Modules and Module Composition. ### 3. Multiple Predictor Types -Choose the right predictor for your task: +Choose the right predictor for the task: -**Predict**: Basic LLM inference with type-safe inputs/outputs -```ruby -predictor = DSPy::Predict.new(TaskSignature) -result = predictor.forward(input: "data") -``` +| Predictor | Use Case | Example | +|-----------|----------|---------| +| **Predict** | Simple tasks, classification, extraction | `DSPy::Predict.new(Sig)` | +| **ChainOfThought** | Complex reasoning, analysis | `DSPy::ChainOfThought.new(Sig)` | +| **ReAct** | Tasks requiring external tools | `DSPy::ReAct.new(Sig, tools: [...])` | +| **CodeAct** | Tasks best solved with generated code | `DSPy::CodeAct.new(Sig)` | -**ChainOfThought**: Adds automatic reasoning for improved accuracy -```ruby -predictor = DSPy::ChainOfThought.new(TaskSignature) -result = predictor.forward(input: "data") -# Returns: { reasoning: "...", output: "..." } -``` - -**ReAct**: Tool-using agents with iterative reasoning -```ruby -predictor = DSPy::ReAct.new( - TaskSignature, - tools: [SearchTool.new, CalculatorTool.new], - max_iterations: 5 -) -``` - -**CodeAct**: Dynamic code generation (requires `dspy-code_act` gem) -```ruby -predictor = DSPy::CodeAct.new(TaskSignature) -result = predictor.forward(task: "Calculate factorial of 5") -``` - -**When to use each**: -- **Predict**: Simple tasks, classification, extraction -- **ChainOfThought**: Complex reasoning, analysis, multi-step thinking -- **ReAct**: Tasks requiring external tools (search, calculation, API calls) -- **CodeAct**: Tasks best solved with generated code - -**Full documentation**: See `references/core-concepts.md` section on Predictors. +**Full documentation**: See [core-concepts.md](./references/core-concepts.md) section on Predictors. ### 4. LLM Provider Configuration Support for OpenAI, Anthropic Claude, Google Gemini, Ollama, and OpenRouter. -**Quick configuration examples**: ```ruby # OpenAI DSPy.configure do |c| @@ -165,48 +117,28 @@ DSPy.configure do |c| api_key: ENV['ANTHROPIC_API_KEY']) end -# Google Gemini -DSPy.configure do |c| - c.lm = DSPy::LM.new('gemini/gemini-1.5-pro', - api_key: ENV['GOOGLE_API_KEY']) -end - # Local Ollama (free, private) DSPy.configure do |c| c.lm = DSPy::LM.new('ollama/llama3.1') end ``` -**Templates**: See `assets/config-template.rb` for comprehensive examples including: -- Environment-based configuration -- Multi-model setups for different tasks -- Configuration with observability (OpenTelemetry, Langfuse) -- Retry logic and fallback strategies -- Budget tracking -- Rails initializer patterns - **Provider compatibility matrix**: | Feature | OpenAI | Anthropic | Gemini | Ollama | |---------|--------|-----------|--------|--------| | Structured Output | ✅ | ✅ | ✅ | ✅ | | Vision (Images) | ✅ | ✅ | ✅ | ⚠️ Limited | -| Image URLs | ✅ | ❌ | ❌ | ❌ | | Tool Calling | ✅ | ✅ | ✅ | Varies | -**Cost optimization strategy**: -- Development: Ollama (free) or gpt-4o-mini (cheap) -- Testing: gpt-4o-mini with temperature=0.0 -- Production simple tasks: gpt-4o-mini, claude-3-haiku, gemini-1.5-flash -- Production complex tasks: gpt-4o, claude-3-5-sonnet, gemini-1.5-pro +**Templates**: See [config-template.rb](./assets/config-template.rb) for environment-based configuration, multi-model setups, and observability. -**Full documentation**: See `references/providers.md` for all configuration options, provider-specific features, and troubleshooting. +**Full documentation**: See [providers.md](./references/providers.md) for all configuration options and troubleshooting. ### 5. Multimodal & Vision Support Process images alongside text using the unified `DSPy::Image` interface. -**Quick reference**: ```ruby class VisionSignature < DSPy::Signature description "Analyze image and answer questions" @@ -228,30 +160,12 @@ result = predictor.forward( ) ``` -**Image loading methods**: -```ruby -# From file -DSPy::Image.from_file("path/to/image.jpg") - -# From URL (OpenAI only) -DSPy::Image.from_url("https://example.com/image.jpg") - -# From base64 -DSPy::Image.from_base64(base64_data, mime_type: "image/jpeg") -``` - -**Provider support**: -- OpenAI: Full support including URLs -- Anthropic, Gemini: Base64 or file loading only -- Ollama: Limited multimodal depending on model - -**Full documentation**: See `references/core-concepts.md` section on Multimodal Support. +**Full documentation**: See [core-concepts.md](./references/core-concepts.md) section on Multimodal Support. ### 6. Testing LLM Applications Write standard RSpec tests for LLM logic. -**Quick reference**: ```ruby RSpec.describe EmailClassifier do before do @@ -269,43 +183,20 @@ RSpec.describe EmailClassifier do ) expect(result[:category]).to eq('Technical') - expect(result[:priority]).to be_in(['High', 'Medium', 'Low']) end end ``` -**Testing patterns**: -- Mock LLM responses for unit tests -- Use VCR for deterministic API testing -- Test type safety and validation -- Test edge cases (empty inputs, special characters, long texts) -- Integration test complete workflows +**Full documentation**: See [optimization.md](./references/optimization.md) section on Testing. -**Full documentation**: See `references/optimization.md` section on Testing. +### 7. Optimization & Observability -### 7. Optimization & Improvement - -Automatically improve prompts and modules using optimization techniques. +Automatically improve prompts and track performance in production. **MIPROv2 optimization**: ```ruby require 'dspy/mipro' -# Define evaluation metric -def accuracy_metric(example, prediction) - example[:expected_output][:category] == prediction[:category] ? 1.0 : 0.0 -end - -# Prepare training data -training_examples = [ - { - input: { email_subject: "...", email_body: "..." }, - expected_output: { category: 'Technical' } - }, - # More examples... -] - -# Run optimization optimizer = DSPy::MIPROv2.new( metric: method(:accuracy_metric), num_candidates: 10 @@ -317,51 +208,9 @@ optimized_module = optimizer.compile( ) ``` -**A/B testing different approaches**: -```ruby -# Test ChainOfThought vs ReAct -approach_a_score = evaluate_approach(ChainOfThoughtModule, test_set) -approach_b_score = evaluate_approach(ReActModule, test_set) -``` +**OpenTelemetry/Langfuse integration** for production monitoring. -**Full documentation**: See `references/optimization.md` section on Optimization. - -### 8. Observability & Monitoring - -Track performance, token usage, and behavior in production. - -**OpenTelemetry integration**: -```ruby -require 'opentelemetry/sdk' - -OpenTelemetry::SDK.configure do |c| - c.service_name = 'my-dspy-app' - c.use_all -end - -# DSPy automatically creates traces -``` - -**Langfuse tracing**: -```ruby -DSPy.configure do |c| - c.lm = DSPy::LM.new('openai/gpt-4o-mini', - api_key: ENV['OPENAI_API_KEY']) - - c.langfuse = { - public_key: ENV['LANGFUSE_PUBLIC_KEY'], - secret_key: ENV['LANGFUSE_SECRET_KEY'] - } -end -``` - -**Custom monitoring**: -- Token tracking -- Performance monitoring -- Error rate tracking -- Custom logging - -**Full documentation**: See `references/optimization.md` section on Observability. +**Full documentation**: See [optimization.md](./references/optimization.md) for optimization techniques and observability setup. ## Quick Start Workflow @@ -372,7 +221,7 @@ end gem install dspy dspy-openai # or dspy-anthropic, dspy-gemini ``` -2. **Configure LLM provider** (see `assets/config-template.rb`): +2. **Configure LLM provider** (see [config-template.rb](./assets/config-template.rb)): ```ruby require 'dspy' @@ -382,7 +231,7 @@ DSPy.configure do |c| end ``` -3. **Create a signature** (see `assets/signature-template.rb`): +3. **Create a signature** (see [signature-template.rb](./assets/signature-template.rb)): ```ruby class MySignature < DSPy::Signature description "Clear description of task" @@ -397,7 +246,7 @@ class MySignature < DSPy::Signature end ``` -4. **Create a module** (see `assets/module-template.rb`): +4. **Create a module** (see [module-template.rb](./assets/module-template.rb)): ```ruby class MyModule < DSPy::Module def initialize @@ -413,182 +262,44 @@ end 5. **Use the module**: ```ruby -module_instance = MyModule.new -result = module_instance.forward(input_field: "test") +result = MyModule.new.forward(input_field: "test") puts result[:output_field] ``` -6. **Add tests** (see `references/optimization.md`): -```ruby -RSpec.describe MyModule do - it 'produces expected output' do - result = MyModule.new.forward(input_field: "test") - expect(result[:output_field]).to be_a(String) - end -end -``` - ### For Rails Applications -1. **Add to Gemfile**: -```ruby -gem 'dspy' -gem 'dspy-openai' # or other provider -``` - -2. **Create initializer** at `config/initializers/dspy.rb` (see `assets/config-template.rb` for full example): -```ruby -require 'dspy' - -DSPy.configure do |c| - c.lm = DSPy::LM.new('openai/gpt-4o-mini', - api_key: ENV['OPENAI_API_KEY']) -end -``` - -3. **Create modules in** `app/llm/` directory: -```ruby -# app/llm/email_classifier.rb -class EmailClassifier < DSPy::Module - # Implementation here -end -``` - -4. **Use in controllers/services**: -```ruby -class EmailsController < ApplicationController - def classify - classifier = EmailClassifier.new - result = classifier.forward( - email_subject: params[:subject], - email_body: params[:body] - ) - render json: result - end -end -``` - -## Common Patterns - -### Pattern: Multi-Step Analysis Pipeline - -```ruby -class AnalysisPipeline < DSPy::Module - def initialize - super - @extract = DSPy::Predict.new(ExtractSignature) - @analyze = DSPy::ChainOfThought.new(AnalyzeSignature) - @summarize = DSPy::Predict.new(SummarizeSignature) - end - - def forward(text:) - extracted = @extract.forward(text: text) - analyzed = @analyze.forward(data: extracted[:data]) - @summarize.forward(analysis: analyzed[:result]) - end -end -``` - -### Pattern: Agent with Tools - -```ruby -class ResearchAgent < DSPy::Module - def initialize - super - @agent = DSPy::ReAct.new( - ResearchSignature, - tools: [ - WebSearchTool.new, - DatabaseQueryTool.new, - SummarizerTool.new - ], - max_iterations: 10 - ) - end - - def forward(question:) - @agent.forward(question: question) - end -end - -class WebSearchTool < DSPy::Tool - def call(query:) - results = perform_search(query) - { results: results } - end -end -``` - -### Pattern: Conditional Routing - -```ruby -class SmartRouter < DSPy::Module - def initialize - super - @classifier = DSPy::Predict.new(ClassifySignature) - @simple_handler = SimpleModule.new - @complex_handler = ComplexModule.new - end - - def forward(input:) - classification = @classifier.forward(text: input) - - if classification[:complexity] == 'Simple' - @simple_handler.forward(input: input) - else - @complex_handler.forward(input: input) - end - end -end -``` - -### Pattern: Retry with Fallback - -```ruby -class RobustModule < DSPy::Module - MAX_RETRIES = 3 - - def forward(input, retry_count: 0) - begin - @predictor.forward(input) - rescue DSPy::ValidationError => e - if retry_count < MAX_RETRIES - sleep(2 ** retry_count) - forward(input, retry_count: retry_count + 1) - else - # Fallback to default or raise - raise - end - end - end -end -``` +1. Add to Gemfile: `gem 'dspy'` and `gem 'dspy-openai'` +2. Create initializer at `config/initializers/dspy.rb` +3. Create modules in `app/llm/` directory +4. Use in controllers/services -## Resources +## Implementation Checklist -This skill includes comprehensive reference materials and templates: +When implementing DSPy.rb features: -### References (load as needed for detailed information) +- [ ] **Signature defined** with clear description and typed fields +- [ ] **Module created** extending `DSPy::Module` with `forward` method +- [ ] **Provider configured** with appropriate API key +- [ ] **Error handling** for LLM failures and validation errors +- [ ] **Tests written** covering expected outputs and edge cases +- [ ] **Cost optimization** considered (use cheaper models for development) +- [ ] **Observability** added for production (OpenTelemetry or Langfuse) -- [core-concepts.md](./references/core-concepts.md): Complete guide to signatures, modules, predictors, multimodal support, and best practices -- [providers.md](./references/providers.md): All LLM provider configurations, compatibility matrix, cost optimization, and troubleshooting -- [optimization.md](./references/optimization.md): Testing patterns, optimization techniques, observability setup, and monitoring +## References -### Assets (templates for quick starts) +### Reference Documentation -- [signature-template.rb](./assets/signature-template.rb): Examples of signatures including basic, vision, sentiment analysis, and code generation -- [module-template.rb](./assets/module-template.rb): Module patterns including pipelines, agents, error handling, caching, and state management -- [config-template.rb](./assets/config-template.rb): Configuration examples for all providers, environments, observability, and production patterns +| File | Purpose | +|------|---------| +| [core-concepts.md](./references/core-concepts.md) | Signatures, modules, predictors, multimodal support | +| [providers.md](./references/providers.md) | LLM provider configurations, compatibility, troubleshooting | +| [optimization.md](./references/optimization.md) | Testing patterns, optimization, observability | +| [common-patterns.md](./references/common-patterns.md) | Multi-step pipelines, agents, routing, retry logic | -## When to Use This Skill +### Assets (Templates) -Trigger this skill when: -- Implementing LLM-powered features in Ruby applications -- Creating type-safe interfaces for AI operations -- Building agent systems with tool usage -- Setting up or troubleshooting LLM providers -- Optimizing prompts and improving accuracy -- Testing LLM functionality -- Adding observability to AI applications -- Converting from manual prompt engineering to programmatic approach -- Debugging DSPy.rb code or configuration issues +| File | Purpose | +|------|---------| +| [signature-template.rb](./assets/signature-template.rb) | Signature examples: basic, vision, sentiment, code generation | +| [module-template.rb](./assets/module-template.rb) | Module patterns: pipelines, agents, caching, state management | +| [config-template.rb](./assets/config-template.rb) | Configuration for all providers, environments, production | diff --git a/plugins/compound-engineering/skills/dspy-ruby/references/common-patterns.md b/plugins/compound-engineering/skills/dspy-ruby/references/common-patterns.md new file mode 100644 index 0000000..28f3c47 --- /dev/null +++ b/plugins/compound-engineering/skills/dspy-ruby/references/common-patterns.md @@ -0,0 +1,168 @@ +# Common Patterns Reference + +## Multi-Step Analysis Pipeline + +Chain multiple modules for complex workflows: + +```ruby +class AnalysisPipeline < DSPy::Module + def initialize + super + @extract = DSPy::Predict.new(ExtractSignature) + @analyze = DSPy::ChainOfThought.new(AnalyzeSignature) + @summarize = DSPy::Predict.new(SummarizeSignature) + end + + def forward(text:) + extracted = @extract.forward(text: text) + analyzed = @analyze.forward(data: extracted[:data]) + @summarize.forward(analysis: analyzed[:result]) + end +end +``` + +## Agent with Tools + +Create agents that use external tools: + +```ruby +class ResearchAgent < DSPy::Module + def initialize + super + @agent = DSPy::ReAct.new( + ResearchSignature, + tools: [ + WebSearchTool.new, + DatabaseQueryTool.new, + SummarizerTool.new + ], + max_iterations: 10 + ) + end + + def forward(question:) + @agent.forward(question: question) + end +end + +class WebSearchTool < DSPy::Tool + def call(query:) + results = perform_search(query) + { results: results } + end +end +``` + +## Conditional Routing + +Route to different handlers based on classification: + +```ruby +class SmartRouter < DSPy::Module + def initialize + super + @classifier = DSPy::Predict.new(ClassifySignature) + @simple_handler = SimpleModule.new + @complex_handler = ComplexModule.new + end + + def forward(input:) + classification = @classifier.forward(text: input) + + if classification[:complexity] == 'Simple' + @simple_handler.forward(input: input) + else + @complex_handler.forward(input: input) + end + end +end +``` + +## Retry with Fallback + +Handle failures with exponential backoff: + +```ruby +class RobustModule < DSPy::Module + MAX_RETRIES = 3 + + def forward(input, retry_count: 0) + begin + @predictor.forward(input) + rescue DSPy::ValidationError => e + if retry_count < MAX_RETRIES + sleep(2 ** retry_count) + forward(input, retry_count: retry_count + 1) + else + raise + end + end + end +end +``` + +## Batch Processing + +Process multiple items efficiently: + +```ruby +class BatchProcessor < DSPy::Module + def initialize + super + @predictor = DSPy::Predict.new(ItemSignature) + end + + def forward(items:) + items.map do |item| + @predictor.forward(item: item) + end + end +end +``` + +## Caching Layer + +Cache expensive operations: + +```ruby +class CachedModule < DSPy::Module + def initialize + super + @predictor = DSPy::Predict.new(ExpensiveSignature) + @cache = {} + end + + def forward(input:) + cache_key = input.hash + return @cache[cache_key] if @cache.key?(cache_key) + + result = @predictor.forward(input: input) + @cache[cache_key] = result + result + end +end +``` + +## Stateful Conversation + +Maintain context across interactions: + +```ruby +class ConversationModule < DSPy::Module + def initialize + super + @predictor = DSPy::Predict.new(ConversationSignature) + @history = [] + end + + def forward(message:) + result = @predictor.forward( + message: message, + history: @history.join("\n") + ) + @history << "User: #{message}" + @history << "Assistant: #{result[:response]}" + result + end +end +``` diff --git a/plugins/compound-engineering/skills/every-style-editor/SKILL.md b/plugins/compound-engineering/skills/every-style-editor/SKILL.md index bbc2964..73519ce 100644 --- a/plugins/compound-engineering/skills/every-style-editor/SKILL.md +++ b/plugins/compound-engineering/skills/every-style-editor/SKILL.md @@ -1,62 +1,64 @@ --- name: every-style-editor -description: This skill should be used when reviewing or editing copy to ensure adherence to Every's style guide. It provides a systematic line-by-line review process for grammar, punctuation, mechanics, and style guide compliance. +description: This skill should be used when reviewing or editing copy to ensure adherence to Every's style guide. Triggers on "edit for style", "review article", "check grammar", "Every style guide", "proofread", "copy edit", or requests to check written content for grammar, punctuation, mechanics, and style compliance. +license: MIT +allowed-tools: + - Read + - Edit + - Write +metadata: + version: "1.1.0" + category: editing + tags: [style-guide, editing, copy, grammar, proofreading] --- # Every Style Editor -This skill provides a systematic approach to reviewing copy against Every's comprehensive style guide. It transforms Claude into a meticulous line editor and proofreader specializing in grammar, mechanics, and style guide compliance. +## Contents -## When to Use This Skill +- [Overview](#overview) +- [4-Phase Review Process](#4-phase-review-process) +- [Output Format](#output-format) +- [Style Guide Quick Reference](#style-guide-quick-reference) +- [Key Principles](#key-principles) +- [References](#references) -Use this skill when: +## Overview + +This skill provides a systematic approach to reviewing copy against Every's comprehensive style guide. It transforms Claude into a meticulous line editor specializing in grammar, mechanics, and style guide compliance. + +**Use when:** - Reviewing articles, blog posts, newsletters, or any written content - Ensuring copy follows Every's specific style conventions - Providing feedback on grammar, punctuation, and mechanics -- Flagging deviations from the Every style guide - Preparing clean copy for human editorial review -## Skill Overview - -This skill enables performing a comprehensive review of written content in four phases: - -1. **Initial Assessment** - Understanding context and document type -2. **Detailed Line Edit** - Checking every sentence for compliance -3. **Mechanical Review** - Verifying formatting and consistency -4. **Recommendations** - Providing actionable improvement suggestions +## 4-Phase Review Process -## How to Use This Skill +| Phase | Focus | Actions | +|-------|-------|---------| +| 1. Initial Assessment | Context | Understand document type, audience, tone | +| 2. Detailed Line Edit | Content | Check grammar, punctuation, word choice, style rules | +| 3. Mechanical Review | Formatting | Verify spacing, formatting, numbers, links | +| 4. Recommendations | Actionable | Provide improvement suggestions | -### Step 1: Initial Assessment +### Phase 2: Detailed Line Edit Checklist -Begin by reading the entire piece to understand: -- Document type (article, knowledge base entry, social post, etc.) -- Target audience -- Overall tone and voice -- Content context +- [ ] Sentence structure and grammar correctness +- [ ] Punctuation usage (commas, semicolons, em dashes) +- [ ] Capitalization rules (job titles, headlines) +- [ ] Word choice (overused words, passive voice) +- [ ] Adherence to [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) -### Step 2: Detailed Line Edit +### Phase 3: Mechanical Review Checklist -Review each paragraph systematically, checking for: -- Sentence structure and grammar correctness -- Punctuation usage (commas, semicolons, em dashes, etc.) -- Capitalization rules (especially job titles, headlines) -- Word choice and usage (overused words, passive voice) -- Adherence to Every style guide rules +- [ ] Spacing and formatting consistency +- [ ] Style choices applied uniformly +- [ ] Special elements (lists, quotes, citations) +- [ ] Number formatting (numerals vs. spelled out) +- [ ] Link formatting and descriptions -Reference the complete [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) for specific rules when in doubt. - -### Step 3: Mechanical Review - -Verify: -- Spacing and formatting consistency -- Style choices applied uniformly throughout -- Special elements (lists, quotes, citations) -- Proper use of italics and formatting -- Number formatting (numerals vs. spelled out) -- Link formatting and descriptions - -### Step 4: Output Results +## Output Format Present findings using this structure: @@ -72,63 +74,72 @@ ERRORS FOUND: [total number] DETAILED CORRECTIONS =================== -[For each error found:] - **Location**: [Paragraph #, Sentence #] **Issue Type**: [Grammar/Punctuation/Mechanics/Style Guide] **Original**: "[exact text with error]" **Correction**: "[corrected text]" **Rule Reference**: [Specific style guide rule violated] -**Explanation**: [Brief explanation of why this is an error] --- RECURRING ISSUES =============== -[List patterns of errors that appear multiple times] +[Patterns of errors appearing multiple times] STYLE GUIDE COMPLIANCE CHECKLIST ============================== ✓ [Rule followed correctly] -✗ [Rule violated - with count of violations] +✗ [Rule violated - with count] FINAL RECOMMENDATIONS =================== -[2-3 actionable suggestions for improving the draft] +[2-3 actionable suggestions] ``` -## Style Guide Reference +## Style Guide Quick Reference -The complete Every style guide is included in [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md). Key areas to focus on: +| Category | Rule | +|----------|------| +| Headlines | Title case for headlines, sentence case elsewhere | +| Tone | Active voice, avoid overused words (actually, very, just) | +| Numbers | Spell out one-nine; numerals for 10+ | +| Punctuation | Oxford commas, em dashes without spaces | +| Capitalization | Lowercase job titles, "it" for company, "they" for teams | +| Emphasis | Italics only (no bold for emphasis) | +| Links | 2-4 words, never "click here" | -- **Quick Rules**: Title case for headlines, sentence case elsewhere -- **Tone**: Active voice, avoid overused words (actually, very, just), be specific -- **Numbers**: Spell out one through nine; use numerals for 10+ -- **Punctuation**: Oxford commas, em dashes without spaces, proper quotation mark usage -- **Capitalization**: Lowercase job titles, company as singular (it), teams as plural (they) -- **Emphasis**: Italics only (no bold for emphasis) -- **Links**: 2-4 words, don't say "click here" +**Full style guide:** [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) ## Key Principles -- **Be specific**: Always quote the exact text with the error -- **Reference rules**: Cite the specific style guide rule for each correction -- **Maintain voice**: Preserve the author's voice while correcting errors -- **Prioritize clarity**: Focus on changes that improve readability +- **Be specific**: Quote exact text with errors +- **Reference rules**: Cite specific style guide rule for each correction +- **Maintain voice**: Preserve author's voice while correcting +- **Prioritize clarity**: Focus on changes improving readability - **Be constructive**: Frame feedback to help writers improve -- **Flag ambiguous cases**: When style guide doesn't address an issue, explain options and recommend the clearest choice - -## Common Areas to Focus On - -Based on Every's style guide, pay special attention to: - -- Punctuation (comma usage, semicolons, apostrophes, quotation marks) -- Capitalization (proper nouns, titles, sentence starts) -- Numbers (when to spell out vs. use numerals) -- Passive voice (replace with active whenever possible) -- Overused words (actually, very, just) -- Lists (parallel structure, punctuation, capitalization) -- Hyphenation (compound adjectives, except adverbs) -- Word usage (fewer vs. less, they vs. them) -- Company references (singular "it", teams as plural "they") -- Job title capitalization + +## Common Focus Areas + +Based on Every's style guide: +- Punctuation (commas, semicolons, quotation marks) +- Capitalization (proper nouns, titles) +- Passive voice → active voice +- Parallel structure in lists +- Compound adjective hyphenation +- Company singular ("it") vs. teams plural ("they") + +## Quality Checklist + +Before delivering edited copy: + +- [ ] 4-phase review process completed +- [ ] All errors documented with specific rule references +- [ ] Recurring issues identified and noted +- [ ] Author's voice preserved in corrections +- [ ] Actionable recommendations provided + +## References + +| File | Purpose | +|------|---------| +| [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) | Complete Every style guide (29KB) | diff --git a/plugins/compound-engineering/skills/file-todos/SKILL.md b/plugins/compound-engineering/skills/file-todos/SKILL.md index 793dfdd..64fd3d0 100644 --- a/plugins/compound-engineering/skills/file-todos/SKILL.md +++ b/plugins/compound-engineering/skills/file-todos/SKILL.md @@ -1,35 +1,48 @@ --- name: file-todos -description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes. +description: This skill should be used when managing file-based todos in the todos/ directory. Triggers on "create a todo", "add todo", "triage todos", "list pending items", "manage work items", "track technical debt", or requests to create, complete, or manage development tasks using markdown-based todo files. +license: MIT +allowed-tools: + - Bash + - Read + - Write + - Edit --- # File-Based Todo Tracking Skill +## Contents + +- [Overview](#overview) +- [File Naming Convention](#file-naming-convention) +- [File Structure](#file-structure) +- [Common Workflows](#common-workflows) +- [Key Distinctions](#key-distinctions) +- [References](#references) + ## Overview The `todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections. -This skill should be used when: +**Use when:** - Creating new todos from findings or feedback - Managing todo lifecycle (pending → ready → complete) - Triaging pending items for approval - Checking or managing dependencies - Converting PR comments or code findings into tracked work -- Updating work logs during todo execution ## File Naming Convention -Todo files follow this naming pattern: - ``` {issue_id}-{status}-{priority}-{description}.md ``` -**Components:** -- **issue_id**: Sequential number (001, 002, 003...) - never reused -- **status**: `pending` (needs triage), `ready` (approved), `complete` (done) -- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have) -- **description**: kebab-case, brief description +| Component | Values | Example | +|-----------|--------|---------| +| issue_id | Sequential (001, 002...) | 003 | +| status | pending, ready, complete | ready | +| priority | p1 (critical), p2 (important), p3 (nice-to-have) | p1 | +| description | kebab-case brief description | fix-n-plus-1 | **Examples:** ``` @@ -40,22 +53,13 @@ Todo files follow this naming pattern: ## File Structure -Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos. +Use the template at [todo-template.md](./assets/todo-template.md) when creating new todos. -**Required sections:** -- **Problem Statement** - What is broken, missing, or needs improvement? -- **Findings** - Investigation results, root cause, key discoveries -- **Proposed Solutions** - Multiple options with pros/cons, effort, risk -- **Recommended Action** - Clear plan (filled during triage) -- **Acceptance Criteria** - Testable checklist items -- **Work Log** - Chronological record with date, actions, learnings +**Required sections:** Problem Statement, Findings, Proposed Solutions, Recommended Action, Acceptance Criteria, Work Log -**Optional sections:** -- **Technical Details** - Affected files, related components, DB changes -- **Resources** - Links to errors, tests, PRs, documentation -- **Notes** - Additional context or decisions +**Optional sections:** Technical Details, Resources, Notes -**YAML frontmatter fields:** +**YAML frontmatter:** ```yaml --- status: ready # pending | ready | complete @@ -68,184 +72,47 @@ dependencies: ["001"] # Issue IDs this is blocked by ## Common Workflows -### Creating a New Todo - -**To create a new todo from findings or feedback:** - -1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1` -2. Copy template: `cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md` -3. Edit and fill required sections: - - Problem Statement - - Findings (if from investigation) - - Proposed Solutions (multiple options) - - Acceptance Criteria - - Add initial Work Log entry -4. Determine status: `pending` (needs triage) or `ready` (pre-approved) -5. Add relevant tags for filtering - -**When to create a todo:** -- Requires more than 15-20 minutes of work -- Needs research, planning, or multiple approaches considered -- Has dependencies on other work -- Requires manager approval or prioritization -- Part of larger feature or refactor -- Technical debt needing documentation - -**When to act immediately instead:** -- Issue is trivial (< 15 minutes) -- Complete context available now -- No planning needed -- User explicitly requests immediate action -- Simple bug fix with obvious solution - -### Triaging Pending Items - -**To triage pending todos:** - -1. List pending items: `ls todos/*-pending-*.md` -2. For each todo: - - Read Problem Statement and Findings - - Review Proposed Solutions - - Make decision: approve, defer, or modify priority -3. Update approved todos: - - Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md` - - Update frontmatter: `status: pending` → `status: ready` - - Fill "Recommended Action" section with clear plan - - Adjust priority if different from initial assessment -4. Deferred todos stay in `pending` status - -**Use slash command:** `/triage` for interactive approval workflow - -### Managing Dependencies - -**To track dependencies:** - -```yaml -dependencies: ["002", "005"] # This todo blocked by issues 002 and 005 -dependencies: [] # No blockers - can work immediately -``` - -**To check what blocks a todo:** -```bash -grep "^dependencies:" todos/003-*.md -``` - -**To find what a todo blocks:** -```bash -grep -l 'dependencies:.*"002"' todos/*.md -``` - -**To verify blockers are complete before starting:** -```bash -for dep in 001 002 003; do - [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete" -done -``` - -### Updating Work Logs +### Creating a Todo -**When working on a todo, always add a work log entry:** +1. Get next ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'` +2. Copy template: `cp assets/todo-template.md todos/{ID}-pending-{priority}-{desc}.md` +3. Fill required sections per [todo-template.md](./assets/todo-template.md) +4. Set status: `pending` (needs triage) or `ready` (pre-approved) -```markdown -### YYYY-MM-DD - Session Title +**Create a todo when:** work > 15 min, needs planning, has dependencies, or requires approval. +**Act immediately when:** work < 15 min, context is complete, no approval needed. -**By:** Claude Code / Developer Name - -**Actions:** -- Specific changes made (include file:line references) -- Commands executed -- Tests run -- Results of investigation +### Triaging Pending Items -**Learnings:** -- What worked / what didn't -- Patterns discovered -- Key insights for future work -``` +1. List pending: `ls todos/*-pending-*.md` +2. Review Problem Statement, Findings, Proposed Solutions +3. Approve: rename `pending` → `ready`, update frontmatter, fill Recommended Action +4. Defer: leave as `pending` -Work logs serve as: -- Historical record of investigation -- Documentation of approaches attempted -- Knowledge sharing for team -- Context for future similar work +**Use slash command:** `/triage` for interactive approval workflow ### Completing a Todo -**To mark a todo as complete:** - -1. Verify all acceptance criteria checked off -2. Update Work Log with final session and results -3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md` -4. Update frontmatter: `status: ready` → `status: complete` +1. Verify all acceptance criteria checked +2. Add final Work Log entry with results +3. Rename: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md` +4. Update frontmatter: `status: complete` 5. Check for unblocked work: `grep -l 'dependencies:.*"002"' todos/*-ready-*.md` -6. Commit with issue reference: `feat: resolve issue 002` - -## Integration with Development Workflows - -| Trigger | Flow | Tool | -|---------|------|------| -| Code review | `/workflows:review` → Findings → `/triage` → Todos | Review agent + skill | -| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill | -| Code TODOs | `/resolve_todo_parallel` → Fixes + Complex todos | Agent + skill | -| Planning | Brainstorm → Create todo → Work → Complete | Skill | -| Feedback | Discussion → Create todo → Triage → Work | Skill + slash | - -## Quick Reference Commands - -**Finding work:** -```bash -# List highest priority unblocked work -grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md - -# List all pending items needing triage -ls todos/*-pending-*.md +6. Commit: `feat: resolve issue 002` -# Find next issue ID -ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}' - -# Count by status -for status in pending ready complete; do - echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)" -done -``` - -**Dependency management:** -```bash -# What blocks this todo? -grep "^dependencies:" todos/003-*.md - -# What does this todo block? -grep -l 'dependencies:.*"002"' todos/*.md -``` - -**Searching:** -```bash -# Search by tag -grep -l "tags:.*rails" todos/*.md +## Key Distinctions -# Search by priority -ls todos/*-p1-*.md +| System | Purpose | Location | +|--------|---------|----------| +| **File-todos** (this skill) | Development/project tracking | `todos/` directory | +| **Rails Todo model** | User-facing feature | `app/models/todo.rb` | +| **TodoWrite tool** | In-memory session tracking | Not persisted | -# Full-text search -grep -r "payment" todos/ -``` - -## Key Distinctions +## References -**File-todos system (this skill):** -- Markdown files in `todos/` directory -- Development/project tracking -- Standalone markdown files with YAML frontmatter -- Used by humans and agents - -**Rails Todo model:** -- Database model in `app/models/todo.rb` -- User-facing feature in the application -- Active Record CRUD operations -- Different from this file-based system - -**TodoWrite tool:** -- In-memory task tracking during agent sessions -- Temporary tracking for single conversation -- Not persisted to disk -- Different from both systems above +| File | Purpose | +|------|---------| +| [todo-template.md](./assets/todo-template.md) | Template for new todos | +| [dependency-management.md](./references/dependency-management.md) | Blocking/unblocking work | +| [quick-commands.md](./references/quick-commands.md) | Shell one-liners for common tasks | +| [integration-workflows.md](./references/integration-workflows.md) | Connecting with /triage, /resolve_pr_parallel | diff --git a/plugins/compound-engineering/skills/file-todos/references/dependency-management.md b/plugins/compound-engineering/skills/file-todos/references/dependency-management.md new file mode 100644 index 0000000..d4212e2 --- /dev/null +++ b/plugins/compound-engineering/skills/file-todos/references/dependency-management.md @@ -0,0 +1,43 @@ +# Dependency Management Reference + +## Tracking Dependencies + +```yaml +dependencies: ["002", "005"] # Blocked by issues 002 and 005 +dependencies: [] # No blockers - can work immediately +``` + +## Dependency Commands + +### Check what blocks a todo + +```bash +grep "^dependencies:" todos/003-*.md +``` + +### Find what a todo blocks + +```bash +grep -l 'dependencies:.*"002"' todos/*.md +``` + +### Verify blockers complete before starting + +```bash +for dep in 001 002 003; do + [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete" +done +``` + +### Find unblocked work after completion + +```bash +grep -l 'dependencies:.*"002"' todos/*-ready-*.md +``` + +## Dependency Best Practices + +- Add dependencies during todo creation +- Remove dependencies when blockers complete +- Check for newly unblocked work after completing any todo +- Use empty array `[]` explicitly when no dependencies diff --git a/plugins/compound-engineering/skills/file-todos/references/integration-workflows.md b/plugins/compound-engineering/skills/file-todos/references/integration-workflows.md new file mode 100644 index 0000000..6213255 --- /dev/null +++ b/plugins/compound-engineering/skills/file-todos/references/integration-workflows.md @@ -0,0 +1,40 @@ +# Integration Workflows Reference + +## Workflow Summary + +| Trigger | Example Command | Result | +|---------|-----------------|--------| +| Code review findings | `/triage` | Approves pending todos from review | +| PR comments | `/resolve_pr_parallel` | Creates todos for complex fixes | +| Code TODOs | `/resolve_todo_parallel` | Processes inline TODO comments | +| Planning | Create todo manually | Documents work for later | + +## Code Review Integration + +1. Run `/workflows:review` to generate findings +2. Findings become pending todos +3. Run `/triage` to approve and prioritize +4. Work on ready todos + +## PR Comment Integration + +1. Receive PR feedback with comments +2. Run `/resolve_pr_parallel` to process +3. Simple fixes applied immediately +4. Complex issues become todos + +## Code TODO Integration + +1. Scan codebase for inline TODO comments +2. Run `/resolve_todo_parallel` to process +3. Simple TODOs resolved directly +4. Complex TODOs become tracked items + +## Slash Command Quick Reference + +| Command | Purpose | +|---------|---------| +| `/triage` | Interactive approval of pending todos | +| `/resolve_pr_parallel` | Process PR comments into fixes/todos | +| `/resolve_todo_parallel` | Process inline TODOs into fixes/todos | +| `/workflows:review` | Run code review generating findings | diff --git a/plugins/compound-engineering/skills/file-todos/references/quick-commands.md b/plugins/compound-engineering/skills/file-todos/references/quick-commands.md new file mode 100644 index 0000000..d23a40c --- /dev/null +++ b/plugins/compound-engineering/skills/file-todos/references/quick-commands.md @@ -0,0 +1,47 @@ +# Quick Reference Commands + +## Finding Work + +```bash +# List highest priority unblocked work +grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md + +# List all pending items needing triage +ls todos/*-pending-*.md + +# Find next issue ID +ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}' + +# Count by status +for status in pending ready complete; do + echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)" +done +``` + +## Searching + +```bash +# Search by tag +grep -l "tags:.*rails" todos/*.md + +# Search by priority +ls todos/*-p1-*.md + +# Full-text search +grep -r "payment" todos/ +``` + +## Status Management + +```bash +# Promote pending to ready +mv todos/003-pending-p1-fix-bug.md todos/003-ready-p1-fix-bug.md + +# Complete a todo +mv todos/003-ready-p1-fix-bug.md todos/003-complete-p1-fix-bug.md +``` + +## Frontmatter Updates + +After renaming, update the YAML frontmatter to match: +- `status: pending` → `status: ready` → `status: complete` diff --git a/plugins/compound-engineering/skills/frontend-design/SKILL.md b/plugins/compound-engineering/skills/frontend-design/SKILL.md index a8344c4..457a413 100644 --- a/plugins/compound-engineering/skills/frontend-design/SKILL.md +++ b/plugins/compound-engineering/skills/frontend-design/SKILL.md @@ -1,42 +1,143 @@ --- name: frontend-design -description: This skill should be used when creating distinctive, production-grade frontend interfaces with high design quality. It applies when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. -license: Complete terms in LICENSE.txt +description: This skill should be used when creating distinctive, production-grade frontend interfaces. Triggers on "build a landing page", "create a component", "design a UI", "make a web page", "build frontend", "React component", "Vue component", or requests for visually striking, memorable web interfaces that avoid generic AI aesthetics. +license: MIT +allowed-tools: + - Write + - Edit + - Read +metadata: + version: "1.1.0" + category: design + tags: [frontend, ui, design, css, react, vue] --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +# Frontend Design -The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. +Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. -## Design Thinking +## Contents -Before coding, understand the context and commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? +- [Quick Start](#quick-start) +- [Workflow](#workflow) +- [Aesthetic Directions](#aesthetic-directions) +- [Anti-Patterns](#anti-patterns) +- [References](#references) -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity. +## Quick Start -Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail +**Example: Brutally Minimal Landing Page** -## Frontend Aesthetics Guidelines +```html + + + + + + +

Less is more

+

The power of restraint creates space for what matters.

+ + +``` -Focus on: -- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. -- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. -- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. -- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. -- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. +## Workflow -NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. +### Phase 1: Context Analysis -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. +1. Identify purpose and audience +2. Note technical constraints (framework, performance, accessibility) +3. Choose ONE bold aesthetic direction from the table below -**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. +### Phase 2: Design Commitment -Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision. +| Direction | Character | Best For | +|-----------|-----------|----------| +| Brutally minimal | Sparse, purposeful restraint | Portfolios, luxury brands | +| Maximalist chaos | Dense, layered, energetic | Creative agencies, events | +| Retro-futuristic | Nostalgic tech meets modern | Tech products, gaming | +| Editorial/magazine | Typography-forward, grid-based | Publications, blogs | +| Brutalist/raw | Honest, structural, bold | Art, architecture | +| Soft/pastel | Gentle, approachable, warm | Wellness, children | + +For detailed typography, color palettes, and layout patterns for each direction, see [aesthetic-guides.md](./references/aesthetic-guides.md). + +### Phase 3: Implementation + +1. Implement working code (HTML/CSS/JS, React, Vue) +2. Ensure production-grade functionality +3. Execute aesthetic with precision +4. Validate against checklist below + +## Aesthetic Directions + +### Typography +- Choose distinctive display fonts (avoid Arial, Inter, Roboto, system fonts) +- Pair display font with refined body font +- Use unexpected, characterful choices + +### Color & Theme +- Commit to cohesive aesthetic with CSS variables +- Use dominant colors with sharp accents +- Avoid timid, evenly-distributed palettes + +### Motion +- CSS-only solutions for HTML; Motion library for React +- Focus on high-impact moments (page load, staggered reveals) +- Scroll-triggering and surprising hover states + +### Spatial Composition +- Unexpected layouts, asymmetry, overlap +- Diagonal flow, grid-breaking elements +- Generous negative space OR controlled density + +## Anti-Patterns + +**NEVER use these generic AI aesthetics:** + +- Overused fonts: Inter, Roboto, Arial, Space Grotesk, system fonts +- Cliché schemes: purple gradients on white backgrounds +- Predictable layouts: cookie-cutter component patterns +- Context-free design: lacks specific character for the project + +**Key rule:** No two designs should look the same. Vary themes, fonts, aesthetics. + +## Quality Checklist + +Before delivering: + +- [ ] Bold aesthetic direction chosen and executed +- [ ] Typography is distinctive (not generic system fonts) +- [ ] Color palette is cohesive with CSS variables +- [ ] Motion adds delight without distraction +- [ ] Layout has intentional spatial composition +- [ ] Production-grade and functional +- [ ] Matches implementation complexity to vision + +## References + +| File | Purpose | +|------|---------| +| [aesthetic-guides.md](./references/aesthetic-guides.md) | Detailed typography, colors, layouts for each direction | +| [brutally-minimal.html](./assets/brutally-minimal.html) | Complete example: minimal landing page | +| [retro-futuristic.html](./assets/retro-futuristic.html) | Complete example: synthwave hero section | diff --git a/plugins/compound-engineering/skills/frontend-design/assets/brutally-minimal.html b/plugins/compound-engineering/skills/frontend-design/assets/brutally-minimal.html new file mode 100644 index 0000000..0121724 --- /dev/null +++ b/plugins/compound-engineering/skills/frontend-design/assets/brutally-minimal.html @@ -0,0 +1,71 @@ + + + + + + Brutally Minimal + + + + +

Less is more

+

The power of restraint creates space for what matters. Every element earns its place.

+

Begin the journey

+ + diff --git a/plugins/compound-engineering/skills/frontend-design/assets/retro-futuristic.html b/plugins/compound-engineering/skills/frontend-design/assets/retro-futuristic.html new file mode 100644 index 0000000..a5ad3cc --- /dev/null +++ b/plugins/compound-engineering/skills/frontend-design/assets/retro-futuristic.html @@ -0,0 +1,121 @@ + + + + + + Retro Futuristic + + + + +
+
+

Neon Dreams

+

The future is now

+ +
+
+ + diff --git a/plugins/compound-engineering/skills/frontend-design/references/aesthetic-guides.md b/plugins/compound-engineering/skills/frontend-design/references/aesthetic-guides.md new file mode 100644 index 0000000..ebfa6c0 --- /dev/null +++ b/plugins/compound-engineering/skills/frontend-design/references/aesthetic-guides.md @@ -0,0 +1,182 @@ +# Aesthetic Direction Guides + +Detailed implementation guides for each aesthetic direction. + +## Brutally Minimal + +**Character:** Sparse, purposeful restraint, whisper-quiet luxury + +**Typography:** +- Display: Playfair Display, Cormorant, Libre Baskerville +- Body: EB Garamond, Lora, or Source Serif Pro +- Sizes: Large display (4-6rem), generous line-height (1.8+) + +**Color Palette:** +```css +:root { + --bg: #fafafa; + --text: #1a1a1a; + --accent: #000; + --muted: #888; +} +``` + +**Layout Patterns:** +- Generous whitespace (8-12rem margins) +- Single-column reading experience +- Hidden navigation, minimal chrome +- Content as hero + +**Motion:** Slow, subtle fades (0.5s+ duration) + +--- + +## Maximalist Chaos + +**Character:** Dense, layered, energetic, overwhelming in the best way + +**Typography:** +- Display: Clash Display, Cabinet Grotesk, Obviously Wide +- Body: DM Sans, General Sans +- Sizes: Oversized (8-12rem), overlapping, rotated + +**Color Palette:** +```css +:root { + --primary: #ff2d55; + --secondary: #5856d6; + --tertiary: #ff9500; + --dark: #1c1c1e; + --light: #f2f2f7; +} +``` + +**Layout Patterns:** +- Overlapping elements +- Broken grids +- Mixed media (images, text, shapes colliding) +- Scroll-jacking encouraged + +**Motion:** Fast, bouncy, staggered animations (spring physics) + +--- + +## Retro-Futuristic + +**Character:** Nostalgic tech meets modern, synthwave vibes + +**Typography:** +- Display: Orbitron, Audiowide, Syncopate +- Body: Space Mono, JetBrains Mono +- Sizes: Tech-terminal feel (monospace emphasis) + +**Color Palette:** +```css +:root { + --bg: #0a0a0a; + --neon-pink: #ff2a6d; + --neon-cyan: #00fff0; + --purple: #9d4edd; + --grid: rgba(255, 255, 255, 0.1); +} +``` + +**Layout Patterns:** +- Grid overlays +- Scanline effects +- CRT monitor aesthetics +- Perspective grids + +**Motion:** Glitch effects, flicker, retro transitions + +--- + +## Editorial/Magazine + +**Character:** Typography-forward, grid-based, sophisticated + +**Typography:** +- Display: Freight Big Pro, Chronicle Display, Canela +- Body: Lyon Text, Untitled Serif, Freight Text +- Sizes: Dramatic headlines (5-8rem), refined body (18-20px) + +**Color Palette:** +```css +:root { + --bg: #fff; + --text: #1a1a1a; + --accent: #c41e3a; + --secondary: #0066cc; + --rule: #e5e5e5; +} +``` + +**Layout Patterns:** +- Strong grid (12-16 columns) +- Pull quotes +- Drop caps +- Image bleeds +- Varied column widths + +**Motion:** Page-turn effects, text reveals, image parallax + +--- + +## Brutalist/Raw + +**Character:** Honest, structural, bold, unapologetically digital + +**Typography:** +- Display: Neue Haas Grotesk, Monument Extended, Druk +- Body: Helvetica Neue, Aktiv Grotesk +- Sizes: Extreme scale contrast + +**Color Palette:** +```css +:root { + --bg: #fff; + --text: #000; + --accent: #0000ff; + --warning: #ff0000; +} +``` + +**Layout Patterns:** +- Visible borders +- Raw HTML feel +- Exposed structure +- Browser defaults embraced +- Table layouts (ironically) + +**Motion:** Minimal, functional only + +--- + +## Soft/Pastel + +**Character:** Gentle, approachable, warm, friendly + +**Typography:** +- Display: Poppins, Nunito, Quicksand +- Body: Lato, Open Sans, Mulish +- Sizes: Comfortable (1.2-1.5rem), generous spacing + +**Color Palette:** +```css +:root { + --bg: #fef6f0; + --primary: #e8b4bc; + --secondary: #a8d8ea; + --accent: #aa96da; + --text: #4a4a4a; +} +``` + +**Layout Patterns:** +- Rounded corners (16-24px) +- Soft shadows +- Ample padding +- Card-based layouts +- Floating elements + +**Motion:** Gentle bounces, soft fades, subtle scale diff --git a/plugins/compound-engineering/skills/gemini-imagegen/SKILL.md b/plugins/compound-engineering/skills/gemini-imagegen/SKILL.md index e9e54b8..40d4bcf 100644 --- a/plugins/compound-engineering/skills/gemini-imagegen/SKILL.md +++ b/plugins/compound-engineering/skills/gemini-imagegen/SKILL.md @@ -1,26 +1,63 @@ --- name: gemini-imagegen -description: This skill should be used when generating and editing images using the Gemini API (Nano Banana Pro). It applies when creating images from text prompts, editing existing images, applying style transfers, generating logos with text, creating stickers, product mockups, or any image generation/manipulation task. Supports text-to-image, image editing, multi-turn refinement, and composition from multiple reference images. +description: This skill should be used when generating or editing images with the Gemini API. Triggers on "generate image", "create image with Gemini", "edit image", "image generation", "text-to-image", "style transfer", "multi-turn image refinement", or requests to use Google's Gemini for visual content creation. +license: MIT +allowed-tools: + - Bash + - Read + - Write --- -# Gemini Image Generation (Nano Banana Pro) +# Gemini Image Generation -Generate and edit images using Google's Gemini API. The environment variable `GEMINI_API_KEY` must be set. +Generate and edit images using Google's Gemini API. -## Default Model +## Contents -| Model | Resolution | Best For | -|-------|------------|----------| -| `gemini-3-pro-image-preview` | 1K-4K | All image generation (default) | +- [Environment Setup](#environment-setup) +- [Ready-to-Use Scripts](#ready-to-use-scripts) +- [Models](#models) +- [Quick Reference](#quick-reference) +- [Core API Pattern](#core-api-pattern) +- [Prompting Best Practices](#prompting-best-practices) +- [File Format Warning](#file-format-warning) -**Note:** Always use this Pro model. Only use a different model if explicitly requested. +## Environment Setup + +**Required:** Set `GEMINI_API_KEY` environment variable. + +**Dependencies:** Install from [requirements.txt](./requirements.txt): +```bash +pip install -r requirements.txt +``` + +## Ready-to-Use Scripts + +The following CLI scripts are available in [scripts/](./scripts/): + +| Script | Purpose | Usage | +|--------|---------|-------| +| [generate_image.py](./scripts/generate_image.py) | Text-to-image generation | `python scripts/generate_image.py "prompt" output.jpg` | +| [edit_image.py](./scripts/edit_image.py) | Edit existing images | `python scripts/edit_image.py input.jpg "edit instruction" output.jpg` | +| [compose_images.py](./scripts/compose_images.py) | Combine multiple images | `python scripts/compose_images.py "instruction" out.jpg img1.jpg img2.jpg` | +| [multi_turn_chat.py](./scripts/multi_turn_chat.py) | Interactive refinement | `python scripts/multi_turn_chat.py` | +| [gemini_images.py](./scripts/gemini_images.py) | Python library | `from gemini_images import GeminiImageGenerator` | + +## Models + +| Model | Speed | Quality | Best For | +|-------|-------|---------|----------| +| `gemini-2.5-flash-image` | Fast | Good | Previews, iteration | +| `gemini-3-pro-image-preview` | Slower | Best | Final outputs, 4K | + +**Default:** Scripts use flash for speed. Use `--model gemini-3-pro-image-preview` for production quality. ## Quick Reference ### Default Settings -- **Model:** `gemini-3-pro-image-preview` -- **Resolution:** 1K (default, options: 1K, 2K, 4K) -- **Aspect Ratio:** 1:1 (default) +- **Model:** `gemini-2.5-flash-image` (scripts) / `gemini-3-pro-image-preview` (pro) +- **Resolution:** 1K (options: 1K, 2K, 4K) +- **Aspect Ratio:** 1:1 ### Available Aspect Ratios `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` @@ -30,31 +67,18 @@ Generate and edit images using Google's Gemini API. The environment variable `GE ## Core API Pattern -```python -import os -from google import genai -from google.genai import types +For complete implementations, see [generate_image.py](./scripts/generate_image.py). -client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) +Quick inline example: -# Basic generation (1K, 1:1 - defaults) -response = client.models.generate_content( - model="gemini-3-pro-image-preview", - contents=["Your prompt here"], - config=types.GenerateContentConfig( - response_modalities=['TEXT', 'IMAGE'], - ), -) +```python +from gemini_images import GeminiImageGenerator -for part in response.parts: - if part.text: - print(part.text) - elif part.inline_data: - image = part.as_image() - image.save("output.png") +gen = GeminiImageGenerator() +gen.generate("A sunset over mountains", "sunset.jpg") ``` -## Custom Resolution & Aspect Ratio +### Custom Resolution & Aspect Ratio ```python from google.genai import types @@ -65,48 +89,16 @@ response = client.models.generate_content( config=types.GenerateContentConfig( response_modalities=['TEXT', 'IMAGE'], image_config=types.ImageConfig( - aspect_ratio="16:9", # Wide format - image_size="2K" # Higher resolution + aspect_ratio="16:9", + image_size="2K" ), ) ) ``` -### Resolution Examples +### Editing Images -```python -# 1K (default) - Fast, good for previews -image_config=types.ImageConfig(image_size="1K") - -# 2K - Balanced quality/speed -image_config=types.ImageConfig(image_size="2K") - -# 4K - Maximum quality, slower -image_config=types.ImageConfig(image_size="4K") -``` - -### Aspect Ratio Examples - -```python -# Square (default) -image_config=types.ImageConfig(aspect_ratio="1:1") - -# Landscape wide -image_config=types.ImageConfig(aspect_ratio="16:9") - -# Ultra-wide panoramic -image_config=types.ImageConfig(aspect_ratio="21:9") - -# Portrait -image_config=types.ImageConfig(aspect_ratio="9:16") - -# Photo standard -image_config=types.ImageConfig(aspect_ratio="4:3") -``` - -## Editing Images - -Pass existing images with text prompts: +Use [edit_image.py](./scripts/edit_image.py) or: ```python from PIL import Image @@ -115,29 +107,21 @@ img = Image.open("input.png") response = client.models.generate_content( model="gemini-3-pro-image-preview", contents=["Add a sunset to this scene", img], - config=types.GenerateContentConfig( - response_modalities=['TEXT', 'IMAGE'], - ), + config=types.GenerateContentConfig(response_modalities=['TEXT', 'IMAGE']), ) ``` -## Multi-Turn Refinement +### Multi-Turn Refinement -Use chat for iterative editing: +Use [multi_turn_chat.py](./scripts/multi_turn_chat.py) for interactive sessions or: ```python -from google.genai import types - chat = client.chats.create( model="gemini-3-pro-image-preview", config=types.GenerateContentConfig(response_modalities=['TEXT', 'IMAGE']) ) - response = chat.send_message("Create a logo for 'Acme Corp'") -# Save first image... - response = chat.send_message("Make the text bolder and add a blue gradient") -# Save refined image... ``` ## Prompting Best Practices @@ -161,6 +145,7 @@ Describe lighting setup and surface: ## Advanced Features ### Google Search Grounding + Generate images based on real-time data: ```python @@ -174,64 +159,47 @@ response = client.models.generate_content( ) ``` -### Multiple Reference Images (Up to 14) -Combine elements from multiple sources: +### Multiple Reference Images -```python -response = client.models.generate_content( - model="gemini-3-pro-image-preview", - contents=[ - "Create a group photo of these people in an office", - Image.open("person1.png"), - Image.open("person2.png"), - Image.open("person3.png"), - ], - config=types.GenerateContentConfig( - response_modalities=['TEXT', 'IMAGE'], - ), -) -``` +Use [compose_images.py](./scripts/compose_images.py) to combine up to 14 reference images. -## Important: File Format & Media Type +## File Format Warning -**CRITICAL:** The Gemini API returns images in JPEG format by default. When saving, always use `.jpg` extension to avoid media type mismatches. +**CRITICAL:** Gemini returns JPEG format by default. Always use `.jpg` extension: ```python -# CORRECT - Use .jpg extension (Gemini returns JPEG) +# CORRECT image.save("output.jpg") -# WRONG - Will cause "Image does not match media type" errors -image.save("output.png") # Creates JPEG with PNG extension! +# WRONG - Creates JPEG with PNG extension! +image.save("output.png") ``` -### Converting to PNG (if needed) - -If you specifically need PNG format: +### Converting to PNG ```python -from PIL import Image - -# Generate with Gemini -for part in response.parts: - if part.inline_data: - img = part.as_image() - # Convert to PNG by saving with explicit format - img.save("output.png", format="PNG") +img.save("output.png", format="PNG") ``` -### Verifying Image Format - -Check actual format vs extension with the `file` command: +### Verify Format ```bash -file image.png -# If output shows "JPEG image data" - rename to .jpg! +file image.png # If shows "JPEG image data" - rename to .jpg ``` +## Quality Checklist + +Before delivering generated images: + +- [ ] GEMINI_API_KEY environment variable set +- [ ] Correct model selected (flash for speed, pro for quality) +- [ ] Prompt includes specific details (camera, lighting, style) +- [ ] Output uses `.jpg` extension (Gemini returns JPEG) +- [ ] Image verified with `file` command if format matters + ## Notes - All generated images include SynthID watermarks -- Gemini returns **JPEG format by default** - always use `.jpg` extension -- Image-only mode (`responseModalities: ["IMAGE"]`) won't work with Google Search grounding -- For editing, describe changes conversationally—the model understands semantic masking +- Image-only mode won't work with Google Search grounding +- For editing, describe changes conversationally - Default to 1K resolution for speed; use 2K/4K when quality is critical diff --git a/plugins/compound-engineering/skills/git-worktree/SKILL.md b/plugins/compound-engineering/skills/git-worktree/SKILL.md index d48a6fe..73e7a22 100644 --- a/plugins/compound-engineering/skills/git-worktree/SKILL.md +++ b/plugins/compound-engineering/skills/git-worktree/SKILL.md @@ -1,27 +1,41 @@ --- name: git-worktree -description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles. +description: This skill should be used when managing Git worktrees for isolated parallel development. Triggers on "create worktree", "git worktree", "review PR in isolation", "parallel development", "work on multiple branches", "isolated code review", or requests to work on multiple features simultaneously without switching branches. +license: MIT +allowed-tools: + - Bash + - Read + - Write --- # Git Worktree Manager -This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity. +## Contents -## What This Skill Does +- [Overview](#overview) +- [When to Use](#when-to-use) +- [Commands](#commands) +- [Workflow Examples](#workflow-examples) +- [Integration with Workflows](#integration-with-workflows) +- [References](#references) -- **Create worktrees** from main branch with clear branch names -- **List worktrees** with current status -- **Switch between worktrees** for parallel work -- **Clean up completed worktrees** automatically -- **Interactive confirmations** at each step -- **Automatic .gitignore management** for worktree directory -- **Automatic .env file copying** from main repo to new worktrees +## Overview + +This skill provides worktree management for isolated PR reviews and parallel feature development. + +**Capabilities:** +- Create worktrees from main branch with clear branch names +- List worktrees with current status +- Switch between worktrees for parallel work +- Clean up completed worktrees automatically +- Automatic .gitignore management for worktree directory +- Automatic .env file copying from main repo to new worktrees ## CRITICAL: Always Use the Manager Script -**NEVER call `git worktree add` directly.** Always use the `worktree-manager.sh` script. +**Never call `git worktree add` directly.** Always use the `worktree-manager.sh` script. -The script handles critical setup that raw git commands don't: +The script handles critical setup that raw git commands do not: 1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo 2. Ensures `.worktrees` is in `.gitignore` 3. Creates consistent directory structure @@ -34,106 +48,37 @@ bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh creat git worktree add .worktrees/feature-name -b feature-name main ``` -## When to Use This Skill - -Use this skill in these scenarios: - -1. **Code Review (`/workflows:review`)**: If NOT already on the PR branch, offer worktree for isolated review -2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work -3. **Parallel Development**: When working on multiple features simultaneously -4. **Cleanup**: After completing work in a worktree - -## How to Use - -### In Claude Code Workflows - -The skill is automatically called from `/workflows:review` and `/workflows:work` commands: - -``` -# For review: offers worktree if not on PR branch -# For work: always asks - new branch or worktree? -``` - -### Manual Usage +## When to Use -You can also invoke the skill directly from bash: - -```bash -# Create a new worktree (copies .env files automatically) -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login - -# List all worktrees -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list - -# Switch to a worktree -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login - -# Copy .env files to an existing worktree (if they weren't copied) -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login - -# Clean up completed worktrees -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup -``` +| Scenario | Trigger | +|----------|---------| +| Code Review (`/workflows:review`) | If NOT already on the PR branch, offer worktree for isolated review | +| Feature Work (`/workflows:work`) | Ask if parallel worktree or live branch work is preferred | +| Parallel Development | When working on multiple features simultaneously | +| Cleanup | After completing work in a worktree | ## Commands -### `create [from-branch]` - -Creates a new worktree with the given branch name. +| Command | Purpose | Example | +|---------|---------|---------| +| `create [from]` | Create new worktree | `... create feature-login` | +| `list` / `ls` | List all worktrees | `... list` | +| `switch ` / `go` | Switch to worktree | `... switch feature-login` | +| `copy-env ` | Copy .env files | `... copy-env feature-login` | +| `cleanup` / `clean` | Remove inactive worktrees | `... cleanup` | -**Options:** -- `branch-name` (required): The name for the new branch and worktree -- `from-branch` (optional): Base branch to create from (defaults to `main`) +Full command prefix: `bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh` -**Example:** -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login -``` +### Create Behavior -**What happens:** 1. Checks if worktree already exists 2. Updates the base branch from remote 3. Creates new worktree and branch -4. **Copies all .env files from main repo** (.env, .env.local, .env.test, etc.) +4. Copies all .env files from main repo 5. Shows path for cd-ing to the worktree -### `list` or `ls` - -Lists all available worktrees with their branches and current status. - -**Example:** -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list -``` - -**Output shows:** -- Worktree name -- Branch name -- Which is current (marked with ✓) -- Main repo status +### Cleanup Behavior -### `switch ` or `go ` - -Switches to an existing worktree and cd's into it. - -**Example:** -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login -``` - -**Optional:** -- If name not provided, lists available worktrees and prompts for selection - -### `cleanup` or `clean` - -Interactively cleans up inactive worktrees with confirmation. - -**Example:** -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup -``` - -**What happens:** 1. Lists all inactive worktrees 2. Asks for confirmation 3. Removes selected worktrees @@ -144,17 +89,16 @@ bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh clean ### Code Review with Worktree ```bash -# Claude Code recognizes you're not on the PR branch +# Claude Code recognizes the current branch differs from the PR branch # Offers: "Use worktree for isolated review? (y/n)" -# You respond: yes -# Script runs (copies .env files automatically): +# If confirmed, the script runs (copies .env files automatically): bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name -# You're now in isolated worktree for review with all env vars +# The working directory is now the isolated worktree with all env vars cd .worktrees/pr-123-feature-name -# After review, return to main: +# After review, return to main and cleanup: cd ../.. bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup ``` @@ -162,16 +106,16 @@ bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh clean ### Parallel Feature Development ```bash -# For first feature (copies .env files): +# Create first feature worktree (copies .env files): bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login -# Later, start second feature (also copies .env files): +# Create second feature worktree (also copies .env files): bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications -# List what you have: +# List available worktrees: bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list -# Switch between them as needed: +# Switch between worktrees: bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login # Return to main and cleanup when done: @@ -179,124 +123,46 @@ cd . bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup ``` -## Key Design Principles - -### KISS (Keep It Simple, Stupid) - -- **One manager script** handles all worktree operations -- **Simple commands** with sensible defaults -- **Interactive prompts** prevent accidental operations -- **Clear naming** using branch names directly - -### Opinionated Defaults - -- Worktrees always created from **main** (unless specified) -- Worktrees stored in **.worktrees/** directory -- Branch name becomes worktree name -- **.gitignore** automatically managed - -### Safety First - -- **Confirms before creating** worktrees -- **Confirms before cleanup** to prevent accidental removal -- **Won't remove current worktree** -- **Clear error messages** for issues - ## Integration with Workflows ### `/workflows:review` -Instead of always creating a worktree: - -``` 1. Check current branch 2. If ALREADY on PR branch → stay there, no worktree needed -3. If DIFFERENT branch → offer worktree: - "Use worktree for isolated review? (y/n)" +3. If DIFFERENT branch → offer worktree: "Use worktree for isolated review? (y/n)" - yes → call git-worktree skill - no → proceed with PR diff on current branch -``` ### `/workflows:work` -Always offer choice: - -``` 1. Ask: "How do you want to work? 1. New branch on current worktree (live work) 2. Worktree (parallel work)" +2. Choice 1 → create new branch normally +3. Choice 2 → call git-worktree skill to create from main -2. If choice 1 → create new branch normally -3. If choice 2 → call git-worktree skill to create from main -``` - -## Troubleshooting - -### "Worktree already exists" - -If you see this, the script will ask if you want to switch to it instead. +## Key Principles -### "Cannot remove worktree: it is the current worktree" - -Switch out of the worktree first (to main repo), then cleanup: - -```bash -cd $(git rev-parse --show-toplevel) -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup -``` - -### Lost in a worktree? - -See where you are: - -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list -``` - -### .env files missing in worktree? - -If a worktree was created without .env files (e.g., via raw `git worktree add`), copy them: - -```bash -bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name -``` - -Navigate back to main: - -```bash -cd $(git rev-parse --show-toplevel) -``` - -## Technical Details - -### Directory Structure +- **One manager script** handles all worktree operations +- **Simple commands** with sensible defaults +- **Interactive prompts** prevent accidental operations +- **Worktrees always from main** (unless specified) +- **Worktrees stored in .worktrees/** directory -``` -.worktrees/ -├── feature-login/ # Worktree 1 -│ ├── .git -│ ├── app/ -│ └── ... -├── feature-notifications/ # Worktree 2 -│ ├── .git -│ ├── app/ -│ └── ... -└── ... - -.gitignore (updated to include .worktrees) -``` +## Quality Checklist -### How It Works +Before completing worktree operations: -- Uses `git worktree add` for isolated environments -- Each worktree has its own branch -- Changes in one worktree don't affect others -- Share git history with main repo -- Can push from any worktree +- [ ] Used `worktree-manager.sh` script (not raw `git worktree add`) +- [ ] .env files copied to new worktree +- [ ] .worktrees directory in .gitignore +- [ ] Worktree created from updated base branch +- [ ] Cleanup run after completing work -### Performance +## References -- Worktrees are lightweight (just file system links) -- No repository duplication -- Shared git objects for efficiency -- Much faster than cloning or stashing/switching +| File | Purpose | +|------|---------| +| [worktree-manager.sh](./scripts/worktree-manager.sh) | Manager script for all operations | +| [troubleshooting.md](./references/troubleshooting.md) | Common issues and solutions | +| [technical-details.md](./references/technical-details.md) | Directory structure, performance, internals | diff --git a/plugins/compound-engineering/skills/git-worktree/references/technical-details.md b/plugins/compound-engineering/skills/git-worktree/references/technical-details.md new file mode 100644 index 0000000..f06de52 --- /dev/null +++ b/plugins/compound-engineering/skills/git-worktree/references/technical-details.md @@ -0,0 +1,64 @@ +# Technical Details Reference + +## Directory Structure + +``` +.worktrees/ +├── feature-login/ # Worktree 1 +│ ├── .git +│ ├── app/ +│ └── ... +├── feature-notifications/ # Worktree 2 +│ ├── .git +│ ├── app/ +│ └── ... +└── ... + +.gitignore (updated to include .worktrees) +``` + +## How Worktrees Work + +- Uses `git worktree add` for isolated environments +- Each worktree has its own branch +- Changes in one worktree do not affect others +- Shares git history with main repo +- Can push from any worktree + +## Performance Characteristics + +- Worktrees are lightweight (file system links) +- No repository duplication +- Shared git objects for efficiency +- Creation is faster than cloning or stashing/switching + +## Automatic .env Handling + +The manager script copies these files from main repo to new worktrees: +- `.env` +- `.env.local` +- `.env.test` +- `.env.development` +- `.env.production` +- Any other `.env*` files + +## Integration with Git + +Worktrees share: +- Git objects and history +- Remote configurations +- Git hooks + +Worktrees maintain separately: +- Working directory files +- Index (staging area) +- Current branch/HEAD + +## Cleanup Behavior + +When cleaning up: +1. Lists all non-current worktrees +2. Confirms before removal +3. Removes worktree directory +4. Removes branch if fully merged +5. Prunes stale entries diff --git a/plugins/compound-engineering/skills/git-worktree/references/troubleshooting.md b/plugins/compound-engineering/skills/git-worktree/references/troubleshooting.md new file mode 100644 index 0000000..ef1840d --- /dev/null +++ b/plugins/compound-engineering/skills/git-worktree/references/troubleshooting.md @@ -0,0 +1,68 @@ +# Troubleshooting Reference + +## Common Issues + +### "Worktree already exists" + +The script will ask if switching to the existing worktree is preferred. + +### "Cannot remove worktree: it is the current worktree" + +Switch out of the worktree first (to main repo), then cleanup: + +```bash +cd $(git rev-parse --show-toplevel) +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup +``` + +### Lost in a worktree? + +Check current location and available worktrees: + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list +``` + +Navigate back to main: + +```bash +cd $(git rev-parse --show-toplevel) +``` + +### .env files missing in worktree? + +If a worktree was created without .env files (e.g., via raw `git worktree add`), copy them: + +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-name +``` + +## Advanced Troubleshooting + +### Worktree branch conflicts + +If a branch already exists from a previous worktree: + +```bash +# Delete orphaned branch +git branch -D feature-name + +# Then create worktree again +bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name +``` + +### Locked worktree + +If git reports a worktree is locked: + +```bash +git worktree unlock .worktrees/feature-name +``` + +### Stale worktree entries + +Clean up stale entries from deleted directories: + +```bash +git worktree prune +``` diff --git a/plugins/compound-engineering/skills/rclone/SKILL.md b/plugins/compound-engineering/skills/rclone/SKILL.md index 62c91a3..4d4ed60 100644 --- a/plugins/compound-engineering/skills/rclone/SKILL.md +++ b/plugins/compound-engineering/skills/rclone/SKILL.md @@ -1,150 +1,106 @@ --- name: rclone -description: Upload, sync, and manage files across cloud storage providers using rclone. Use when uploading files (images, videos, documents) to S3, Cloudflare R2, Backblaze B2, Google Drive, Dropbox, or any S3-compatible storage. Triggers on "upload to S3", "sync to cloud", "rclone", "backup files", "upload video/image to bucket", or requests to transfer files to remote storage. +description: This skill should be used when uploading, syncing, or managing files across cloud storage providers using rclone. Triggers on "upload to S3", "sync to cloud", "rclone", "backup files", "upload video/image to bucket", "Cloudflare R2", "Backblaze B2", "Google Drive sync", "Dropbox upload", or requests to transfer files to S3-compatible storage. +license: MIT +allowed-tools: + - Bash + - Read + - Write +metadata: + version: "1.1.0" + category: file-transfer + tags: [cloud-storage, s3, r2, b2, rclone, backup] --- # rclone File Transfer Skill -## Setup Check (Always Run First) +Transfer files to cloud storage using rclone. -Before any rclone operation, verify installation and configuration: +## Contents -```bash -# Check if rclone is installed -command -v rclone >/dev/null 2>&1 && echo "rclone installed: $(rclone version | head -1)" || echo "NOT INSTALLED" - -# List configured remotes -rclone listremotes 2>/dev/null || echo "NO REMOTES CONFIGURED" -``` - -### If rclone is NOT installed - -Guide the user to install: - -```bash -# macOS -brew install rclone - -# Linux (script install) -curl https://rclone.org/install.sh | sudo bash +- [Workflow](#workflow) +- [Quick Commands](#quick-commands) +- [Transfer Checklist](#transfer-checklist) +- [References](#references) -# Or via package manager -sudo apt install rclone # Debian/Ubuntu -sudo dnf install rclone # Fedora -``` +## Workflow -### If NO remotes are configured +### Phase 1: Setup Verification -Walk the user through interactive configuration: +1. Check rclone installation +2. List configured remotes +3. Configure new remote if needed ```bash -rclone config -``` - -**Common provider setup quick reference:** - -| Provider | Type | Key Settings | -|----------|------|--------------| -| AWS S3 | `s3` | access_key_id, secret_access_key, region | -| Cloudflare R2 | `s3` | access_key_id, secret_access_key, endpoint (account_id.r2.cloudflarestorage.com) | -| Backblaze B2 | `b2` | account (keyID), key (applicationKey) | -| DigitalOcean Spaces | `s3` | access_key_id, secret_access_key, endpoint (region.digitaloceanspaces.com) | -| Google Drive | `drive` | OAuth flow (opens browser) | -| Dropbox | `dropbox` | OAuth flow (opens browser) | - -**Example: Configure Cloudflare R2** -```bash -rclone config create r2 s3 \ - provider=Cloudflare \ - access_key_id=YOUR_ACCESS_KEY \ - secret_access_key=YOUR_SECRET_KEY \ - endpoint=ACCOUNT_ID.r2.cloudflarestorage.com \ - acl=private +# Check installation and remotes +command -v rclone >/dev/null 2>&1 && echo "rclone: $(rclone version | head -1)" || echo "NOT INSTALLED" +rclone listremotes 2>/dev/null || echo "NO REMOTES CONFIGURED" ``` -**Example: Configure AWS S3** -```bash -rclone config create aws s3 \ - provider=AWS \ - access_key_id=YOUR_ACCESS_KEY \ - secret_access_key=YOUR_SECRET_KEY \ - region=us-east-1 -``` +### Phase 2: Transfer -## Common Operations +1. Choose operation (copy, sync) +2. Add appropriate flags +3. Execute transfer -### Upload single file ```bash -rclone copy /path/to/file.mp4 remote:bucket/path/ --progress -``` +# Upload file +rclone copy /path/to/file remote:bucket/path/ --progress -### Upload directory -```bash +# Upload directory rclone copy /path/to/folder remote:bucket/folder/ --progress -``` -### Sync directory (mirror, deletes removed files) -```bash +# Sync (mirror with deletes) rclone sync /local/path remote:bucket/path/ --progress ``` -### List remote contents -```bash -rclone ls remote:bucket/ -rclone lsd remote:bucket/ # directories only -``` +### Phase 3: Verification + +1. Check file exists on remote +2. Verify file integrity +3. Troubleshoot if needed -### Check what would be transferred (dry run) ```bash -rclone copy /path remote:bucket/ --dry-run +# Verify upload +rclone check /local/file remote:bucket/file +rclone lsl remote:bucket/path/to/file ``` -## Useful Flags +## Quick Commands -| Flag | Purpose | -|------|---------| -| `--progress` | Show transfer progress | -| `--dry-run` | Preview without transferring | -| `-v` | Verbose output | -| `--transfers=N` | Parallel transfers (default 4) | -| `--bwlimit=RATE` | Bandwidth limit (e.g., `10M`) | -| `--checksum` | Compare by checksum, not size/time | -| `--exclude="*.tmp"` | Exclude patterns | -| `--include="*.mp4"` | Include only matching | -| `--min-size=SIZE` | Skip files smaller than SIZE | -| `--max-size=SIZE` | Skip files larger than SIZE | +| Operation | Command | +|-----------|---------| +| Upload file | `rclone copy file.mp4 remote:bucket/ --progress` | +| Upload folder | `rclone copy ./folder remote:bucket/folder/ --progress` | +| Sync folder | `rclone sync ./local remote:bucket/ --progress` | +| List contents | `rclone ls remote:bucket/` | +| Dry run | `rclone copy ./path remote:bucket/ --dry-run` | +| Large file | `rclone copy big.mp4 remote:bucket/ --s3-chunk-size=64M --progress` | -## Large File Uploads +## Transfer Checklist -For videos and large files, use chunked uploads: +- [ ] rclone installed (`command -v rclone`) +- [ ] Remote configured (`rclone listremotes`) +- [ ] Remote accessible (`rclone lsd remote:`) +- [ ] Transfer completed without errors +- [ ] File verified on remote (`rclone check`) -```bash -# S3 multipart upload (automatic for >200MB) -rclone copy large_video.mp4 remote:bucket/ --s3-chunk-size=64M --progress +## References -# Resume interrupted transfers -rclone copy /path remote:bucket/ --progress --retries=5 -``` +- [Provider Configuration](./references/providers.md) - Setup for S3, R2, B2, Google Drive, Dropbox +- [Operations Reference](./references/operations.md) - All commands and flags +- [Troubleshooting](./references/troubleshooting.md) - Debug and fix common issues -## Verify Upload +## Installation -```bash -# Check file exists and matches -rclone check /local/file remote:bucket/file - -# Get file info -rclone lsl remote:bucket/path/to/file -``` - -## Troubleshooting +If rclone is not installed: ```bash -# Test connection -rclone lsd remote: - -# Debug connection issues -rclone lsd remote: -vv +# macOS +brew install rclone -# Check config -rclone config show remote +# Linux +curl https://rclone.org/install.sh | sudo bash ``` + +Configure a new remote: `rclone config` diff --git a/plugins/compound-engineering/skills/rclone/references/operations.md b/plugins/compound-engineering/skills/rclone/references/operations.md new file mode 100644 index 0000000..f5ee7b0 --- /dev/null +++ b/plugins/compound-engineering/skills/rclone/references/operations.md @@ -0,0 +1,66 @@ +# Common Operations Reference + +## Basic Operations + +### Upload single file +```bash +rclone copy /path/to/file.mp4 remote:bucket/path/ --progress +``` + +### Upload directory +```bash +rclone copy /path/to/folder remote:bucket/folder/ --progress +``` + +### Sync directory (mirror, deletes removed files) +```bash +rclone sync /local/path remote:bucket/path/ --progress +``` + +### List remote contents +```bash +rclone ls remote:bucket/ +rclone lsd remote:bucket/ # directories only +``` + +### Dry run (preview without transferring) +```bash +rclone copy /path remote:bucket/ --dry-run +``` + +## Useful Flags + +| Flag | Purpose | +|------|---------| +| `--progress` | Show transfer progress | +| `--dry-run` | Preview without transferring | +| `-v` | Verbose output | +| `--transfers=N` | Parallel transfers (default 4) | +| `--bwlimit=RATE` | Bandwidth limit (e.g., `10M`) | +| `--checksum` | Compare by checksum, not size/time | +| `--exclude="*.tmp"` | Exclude patterns | +| `--include="*.mp4"` | Include only matching | +| `--min-size=SIZE` | Skip files smaller than SIZE | +| `--max-size=SIZE` | Skip files larger than SIZE | + +## Large File Uploads + +For videos and large files, use chunked uploads: + +```bash +# S3 multipart upload (automatic for >200MB) +rclone copy large_video.mp4 remote:bucket/ --s3-chunk-size=64M --progress + +# Resume interrupted transfers +rclone copy /path remote:bucket/ --progress --retries=5 +``` + +## Verification + +```bash +# Check file exists and matches +rclone check /local/file remote:bucket/file + +# Get file info +rclone lsl remote:bucket/path/to/file +``` diff --git a/plugins/compound-engineering/skills/rclone/references/providers.md b/plugins/compound-engineering/skills/rclone/references/providers.md new file mode 100644 index 0000000..57b64bb --- /dev/null +++ b/plugins/compound-engineering/skills/rclone/references/providers.md @@ -0,0 +1,63 @@ +# Provider Configuration Reference + +## Provider Setup Quick Reference + +| Provider | Type | Key Settings | +|----------|------|--------------| +| AWS S3 | `s3` | access_key_id, secret_access_key, region | +| Cloudflare R2 | `s3` | access_key_id, secret_access_key, endpoint (account_id.r2.cloudflarestorage.com) | +| Backblaze B2 | `b2` | account (keyID), key (applicationKey) | +| DigitalOcean Spaces | `s3` | access_key_id, secret_access_key, endpoint (region.digitaloceanspaces.com) | +| Google Drive | `drive` | OAuth flow (opens browser) | +| Dropbox | `dropbox` | OAuth flow (opens browser) | + +## Configuration Examples + +### Cloudflare R2 + +```bash +rclone config create r2 s3 \ + provider=Cloudflare \ + access_key_id=YOUR_ACCESS_KEY \ + secret_access_key=YOUR_SECRET_KEY \ + endpoint=ACCOUNT_ID.r2.cloudflarestorage.com \ + acl=private +``` + +### AWS S3 + +```bash +rclone config create aws s3 \ + provider=AWS \ + access_key_id=YOUR_ACCESS_KEY \ + secret_access_key=YOUR_SECRET_KEY \ + region=us-east-1 +``` + +### Backblaze B2 + +```bash +rclone config create b2 b2 \ + account=YOUR_KEY_ID \ + key=YOUR_APPLICATION_KEY +``` + +### DigitalOcean Spaces + +```bash +rclone config create spaces s3 \ + provider=DigitalOcean \ + access_key_id=YOUR_ACCESS_KEY \ + secret_access_key=YOUR_SECRET_KEY \ + endpoint=nyc3.digitaloceanspaces.com +``` + +## Interactive Configuration + +For OAuth-based providers (Google Drive, Dropbox): + +```bash +rclone config +``` + +Follow the interactive prompts to complete authentication. diff --git a/plugins/compound-engineering/skills/rclone/references/troubleshooting.md b/plugins/compound-engineering/skills/rclone/references/troubleshooting.md new file mode 100644 index 0000000..b0e78c2 --- /dev/null +++ b/plugins/compound-engineering/skills/rclone/references/troubleshooting.md @@ -0,0 +1,53 @@ +# Troubleshooting Reference + +## Connection Testing + +```bash +# Test connection +rclone lsd remote: + +# Debug connection issues +rclone lsd remote: -vv + +# Check config +rclone config show remote +``` + +## Common Issues + +### "Remote not found" +- Verify remote name: `rclone listremotes` +- Check spelling (remotes are case-sensitive) + +### "Access denied" / "Permission denied" +- Verify credentials: `rclone config show remote` +- Check bucket/path permissions in provider console +- For S3-compatible: verify endpoint URL + +### "Checksum mismatch" +- File may have been modified during transfer +- Use `--checksum` flag to force checksum comparison +- Re-upload with `--ignore-checksum` if source changed + +### "Connection timeout" +- Check network connectivity +- Try with `--timeout=30m` for slow connections +- Use `--retries=5` for unreliable networks + +### "Out of memory" (large transfers) +- Reduce parallel transfers: `--transfers=1` +- Use `--buffer-size=16M` to limit memory +- Split large directories into smaller batches + +## Debug Commands + +```bash +# Full debug output +rclone copy /path remote:bucket/ -vv --log-file=rclone.log + +# Check what would be transferred +rclone copy /path remote:bucket/ --dry-run + +# Compare local vs remote +rclone check /path remote:bucket/ +``` diff --git a/plugins/compound-engineering/skills/skill-creator/SKILL.md b/plugins/compound-engineering/skills/skill-creator/SKILL.md index 4069935..8d51f7c 100644 --- a/plugins/compound-engineering/skills/skill-creator/SKILL.md +++ b/plugins/compound-engineering/skills/skill-creator/SKILL.md @@ -1,209 +1,166 @@ --- name: skill-creator -description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. -license: Complete terms in LICENSE.txt +description: This skill should be used when creating a new skill or updating an existing skill. Triggers on "create a skill", "new skill", "write a skill", "update skill", "skill template", "SKILL.md", or requests to extend Claude's capabilities with specialized knowledge, workflows, or tool integrations. +license: MIT +allowed-tools: + - Bash + - Read + - Write + - Edit +metadata: + version: "1.1.0" + category: development + tags: [skills, creation, templates, workflows] --- # Skill Creator -This skill provides guidance for creating effective skills. +## Contents -## About Skills +- [Overview](#overview) +- [Skill Anatomy](#skill-anatomy) +- [6-Step Creation Process](#6-step-creation-process) +- [Writing Guidelines](#writing-guidelines) +- [References](#references) -Skills are modular, self-contained packages that extend Claude's capabilities by providing -specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific -domains or tasks—they transform Claude from a general-purpose agent into a specialized agent -equipped with procedural knowledge that no model can fully possess. +## Overview -### What Skills Provide +Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge. -1. Specialized workflows - Multi-step procedures for specific domains -2. Tool integrations - Instructions for working with specific file formats or APIs -3. Domain expertise - Company-specific knowledge, schemas, business logic -4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks +**Skills provide:** +- Specialized workflows - Multi-step procedures for specific domains +- Tool integrations - Instructions for working with file formats or APIs +- Domain expertise - Company-specific knowledge, schemas, business logic +- Bundled resources - Scripts, references, and assets for complex tasks -### Anatomy of a Skill +## Skill Anatomy -Every skill consists of a required SKILL.md file and optional bundled resources: +Every skill consists of a required SKILL.md and optional bundled resources: ``` skill-name/ ├── SKILL.md (required) -│ ├── YAML frontmatter metadata (required) -│ │ ├── name: (required) -│ │ └── description: (required) -│ └── Markdown instructions (required) +│ ├── YAML frontmatter (name, description required) +│ └── Markdown instructions └── Bundled Resources (optional) - ├── scripts/ - Executable code (Python/Bash/etc.) - ├── references/ - Documentation intended to be loaded into context as needed - └── assets/ - Files used in output (templates, icons, fonts, etc.) + ├── scripts/ - Executable code + ├── references/ - Documentation loaded as needed + └── assets/ - Files used in output ``` -#### SKILL.md (required) +**Metadata quality:** The `name` and `description` in YAML frontmatter determine when Claude uses the skill. Use third-person: "This skill should be used when..." not "Use this skill when..." -**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when..."). +**Full bundled resources guide:** See [bundled-resources.md](./references/bundled-resources.md) -#### Bundled Resources (optional) +## 6-Step Creation Process -##### Scripts (`scripts/`) +| Step | Action | Skip When | +|------|--------|-----------| +| 1 | Gather concrete usage examples | Already understood | +| 2 | Plan reusable contents | Simple skill | +| 3 | Initialize with `init_skill.py` | Updating existing skill | +| 4 | Edit SKILL.md and resources | N/A | +| 5 | Package with `package_skill.py` | Not distributing | +| 6 | Iterate based on testing | Perfect first time | -Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. +### Step 1: Understanding with Examples -- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed -- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks -- **Benefits**: Token efficient, deterministic, may be executed without loading into context -- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments +Gather concrete examples of skill usage. See [planning-examples.md](./references/planning-examples.md) for detailed guidance. -##### References (`references/`) - -Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking. - -- **When to include**: For documentation that Claude should reference while working -- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications -- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides -- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed -- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md -- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. - -##### Assets (`assets/`) - -Files not intended to be loaded into context, but rather used within the output Claude produces. - -- **When to include**: When the skill needs files that will be used in the final output -- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography -- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified -- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context - -### Progressive Disclosure Design Principle - -Skills use a three-level loading system to manage context efficiently: - -1. **Metadata (name + description)** - Always in context (~100 words) -2. **SKILL.md body** - When skill triggers (<5k words) -3. **Bundled resources** - As needed by Claude (Unlimited*) - -*Unlimited because scripts can be executed without reading into context window. - -## Skill Creation Process - -To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable. - -### Step 1: Understanding the Skill with Concrete Examples - -Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. - -To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. - -For example, when building an image-editor skill, relevant questions include: - -- "What functionality should the image-editor skill support? Editing, rotating, anything else?" -- "Can you give some examples of how this skill would be used?" -- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" +**Key questions:** +- "What functionality should this skill support?" - "What would a user say that should trigger this skill?" +- "Can you give examples of how this skill would be used?" -To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. - -Conclude this step when there is a clear sense of the functionality the skill should support. - -### Step 2: Planning the Reusable Skill Contents - -To turn concrete examples into an effective skill, analyze each example by: - -1. Considering how to execute on the example from scratch -2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly - -Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: - -1. Rotating a PDF requires re-writing the same code each time -2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill - -Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: +### Step 2: Planning Reusable Contents -1. Writing a frontend webapp requires the same boilerplate HTML/React each time -2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill - -Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: - -1. Querying BigQuery requires re-discovering the table schemas and relationships each time -2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill - -To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. +For each example, identify: +- **Scripts:** Code that would be rewritten repeatedly +- **References:** Documentation Claude should reference while working +- **Assets:** Templates or files used in output ### Step 3: Initializing the Skill -At this point, it is time to actually create the skill. - -Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step. - -When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. - -Usage: +Run the initialization script to create a template skill: ```bash scripts/init_skill.py --path ``` -The script: +The script creates: +- SKILL.md template with proper frontmatter and TODOs +- Example `scripts/`, `references/`, `assets/` directories -- Creates the skill directory at the specified path -- Generates a SKILL.md template with proper frontmatter and TODO placeholders -- Creates example resource directories: `scripts/`, `references/`, and `assets/` -- Adds example files in each directory that can be customized or deleted +### Step 4: Editing the Skill -After initialization, customize or remove the generated SKILL.md and example files as needed. +Focus on information that would be beneficial and non-obvious to Claude. -### Step 4: Edit the Skill +**Start with:** Reusable resources (`scripts/`, `references/`, `assets/`) +- May require user input (e.g., brand assets, documentation) +- Delete example files not needed for the skill -When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively. - -#### Start with Reusable Skill Contents - -To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. +**Then update SKILL.md answering:** +1. What is the purpose of the skill? +2. When should the skill be used? +3. How should Claude use the skill's resources? -Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. +### Step 5: Packaging -#### Update SKILL.md +Package the skill for distribution: -**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption. +```bash +scripts/package_skill.py [output-dir] +``` -To complete SKILL.md, answer the following questions: +The script validates then packages: +- YAML frontmatter format and required fields +- Description completeness and quality +- File organization and resource references +- Creates zip file maintaining directory structure -1. What is the purpose of the skill, in a few sentences? -2. When should the skill be used? -3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them. +### Step 6: Iterate -### Step 5: Packaging a Skill +After testing, implement improvements: +1. Use the skill on real tasks +2. Notice struggles or inefficiencies +3. Update SKILL.md or bundled resources +4. Test again -Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements: +## Writing Guidelines -```bash -scripts/package_skill.py -``` +**Use imperative/infinitive form** (verb-first instructions): +- "To accomplish X, do Y" rather than "You should do X" -Optional output directory specification: +**Keep SKILL.md lean:** +- Essential procedural instructions only +- Move detailed reference material to `references/` +- Avoid duplication between SKILL.md and references -```bash -scripts/package_skill.py ./dist -``` +## References -The packaging script will: +### Reference Documentation -1. **Validate** the skill automatically, checking: - - YAML frontmatter format and required fields - - Skill naming conventions and directory structure - - Description completeness and quality - - File organization and resource references +| File | Purpose | +|------|---------| +| [bundled-resources.md](./references/bundled-resources.md) | Scripts, references, assets guide | +| [planning-examples.md](./references/planning-examples.md) | Example analysis for skill planning | -2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution. +### Scripts -If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again. +| Script | Purpose | +|--------|---------| +| [init_skill.py](./scripts/init_skill.py) | Initialize new skill from template | +| [package_skill.py](./scripts/package_skill.py) | Validate and package skill for distribution | +| [quick_validate.py](./scripts/quick_validate.py) | Quick validation of skill structure | -### Step 6: Iterate +## Quality Checklist -After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. +Before publishing a skill: -**Iteration workflow:** -1. Use the skill on real tasks -2. Notice struggles or inefficiencies -3. Identify how SKILL.md or bundled resources should be updated -4. Implement changes and test again +- [ ] YAML frontmatter has valid `name` and `description` +- [ ] Description uses third person ("This skill should be used when...") +- [ ] Description includes trigger keywords +- [ ] SKILL.md under 500 lines +- [ ] References one level deep from SKILL.md +- [ ] All bundled files linked with proper markdown links +- [ ] Tested with real usage scenarios diff --git a/plugins/compound-engineering/skills/skill-creator/references/bundled-resources.md b/plugins/compound-engineering/skills/skill-creator/references/bundled-resources.md new file mode 100644 index 0000000..7cc7efd --- /dev/null +++ b/plugins/compound-engineering/skills/skill-creator/references/bundled-resources.md @@ -0,0 +1,84 @@ +# Bundled Resources Guide + +## Overview + +Skills can include three types of bundled resources: + +| Type | Purpose | Location | +|------|---------|----------| +| Scripts | Executable code for deterministic tasks | `scripts/` | +| References | Documentation loaded as needed | `references/` | +| Assets | Files used in output (templates, images) | `assets/` | + +## Scripts (`scripts/`) + +Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability or repeatedly rewritten. + +**When to include:** +- Same code is being rewritten repeatedly +- Deterministic reliability is needed + +**Examples:** +- `scripts/rotate_pdf.py` for PDF rotation +- `scripts/validate_schema.py` for data validation +- `scripts/generate_report.py` for templated reports + +**Benefits:** +- Token efficient +- Deterministic execution +- May be executed without loading into context + +**Note:** Scripts may still need to be read for patching or environment-specific adjustments. + +## References (`references/`) + +Documentation intended to be loaded as needed into context. + +**When to include:** +- Documentation Claude should reference while working +- Detailed information not needed for every invocation + +**Examples:** +- `references/finance.md` for financial schemas +- `references/api_docs.md` for API specifications +- `references/policies.md` for company policies + +**Best practices:** +- Keep SKILL.md lean, references loaded only when needed +- For large files (>10k words), include grep search patterns in SKILL.md +- Avoid duplication between SKILL.md and references + +**Information placement:** +- SKILL.md: Essential procedural instructions, workflow guidance +- References: Detailed reference material, schemas, examples + +## Assets (`assets/`) + +Files not loaded into context, but used within output Claude produces. + +**When to include:** +- Files needed in final output +- Templates to copy or modify +- Binary files (images, fonts, documents) + +**Examples:** +- `assets/logo.png` for brand assets +- `assets/slides.pptx` for PowerPoint templates +- `assets/frontend-template/` for HTML/React boilerplate +- `assets/font.ttf` for typography + +**Benefits:** +- Separates output resources from documentation +- Enables file use without loading into context + +## Progressive Disclosure Design + +Skills use a three-level loading system: + +| Level | Content | When Loaded | Size | +|-------|---------|-------------|------| +| 1 | Metadata (name + description) | Always | ~100 words | +| 2 | SKILL.md body | When skill triggers | <5k words | +| 3 | Bundled resources | As needed | Unlimited* | + +*Scripts can be executed without reading into context window. diff --git a/plugins/compound-engineering/skills/skill-creator/references/planning-examples.md b/plugins/compound-engineering/skills/skill-creator/references/planning-examples.md new file mode 100644 index 0000000..282a131 --- /dev/null +++ b/plugins/compound-engineering/skills/skill-creator/references/planning-examples.md @@ -0,0 +1,50 @@ +# Planning Examples + +## Step 1: Understanding with Concrete Examples + +To create an effective skill, gather concrete usage examples through questions like: + +- "What functionality should the skill support?" +- "Can you give examples of how this skill would be used?" +- "What would a user say that should trigger this skill?" + +Avoid overwhelming users with too many questions. Start with the most important and follow up as needed. + +**Conclude when:** Clear sense of functionality the skill should support. + +## Step 2: Planning Reusable Contents + +Analyze each example by: +1. Considering how to execute from scratch +2. Identifying helpful scripts, references, and assets for repeated execution + +### Example: PDF Editor Skill + +**Query:** "Help me rotate this PDF" + +**Analysis:** +1. Rotating a PDF requires re-writing the same code each time +2. A `scripts/rotate_pdf.py` script would be helpful + +### Example: Frontend Webapp Builder Skill + +**Query:** "Build me a todo app" or "Build me a dashboard" + +**Analysis:** +1. Writing a frontend webapp requires the same boilerplate HTML/React +2. An `assets/hello-world/` template containing boilerplate would be helpful + +### Example: BigQuery Skill + +**Query:** "How many users have logged in today?" + +**Analysis:** +1. Querying BigQuery requires re-discovering table schemas each time +2. A `references/schema.md` documenting table schemas would be helpful + +## Establishing Skill Contents + +For each concrete example, create a list of reusable resources: +- **Scripts:** Repeatable code tasks +- **References:** Domain knowledge, schemas, documentation +- **Assets:** Templates, boilerplate, binary files