Agent skill

commands-arustydev-ai-5

Create a convert-X-Y skill for translating code between languages

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/commands-arustydev-ai-5

SKILL.md

Create Language Conversion Skill

Create a new one-way language conversion skill (convert-<source>-<target>) that extends meta-convert-dev with language-pair-specific patterns.

Arguments

  • $1 - Source language (lowercase, e.g., typescript, python, golang)
  • $2 - Target language (lowercase, e.g., rust, python, golang)

Quick Reference

Step Action Purpose
0 Check existing Avoid duplicate skills
0.5 Check reverse skill Reference convert-$2-$1 for bidirectional insights
1 Validate args Ensure valid language names
2 Read foundations Understand meta-skill patterns
2.5 Validate 8 Pillars Ensure lang skills have coverage
3 Research pair Gather language-specific mappings
3.5 Assess difficulty Rate language pair complexity
4 Create directory Set up skill location
5 Generate SKILL.md Create from template
6 Populate content Fill in language-specific details
7 Validate skill Run quality checklist
8 Cross-references Suggest related skill updates
9 Report Summary of what was created
10 Feedback Self-review and improvement suggestions

Modes:

  • Create (default) - New skill from scratch
  • Update - Improve existing skill (use --update or detect existing)
  • Quick Start - For experienced users who know the patterns well

Quick Start Mode (Experienced Users)

If you've created multiple conversion skills and are familiar with the 8-pillar validation, APTV workflow, and skill structure:

  1. Validate pillars quickly - Check both lang skills for 8/8 coverage
  2. Skip deep research - Use existing patterns from similar language pairs
  3. Focus on differentiators - What makes THIS pair unique?
  4. Reference existing skills - Borrow heavily from similar conversions

Similar language pair detection:

New Pair Reference Pairs Why Similar
clojure→X python→X, elixir→X Dynamic, functional
X→rust X→go, typescript→rust Static typing, ownership concepts
erlang→X elixir→X BEAM platform, same patterns
scala→X kotlin→X, clojure→X JVM, functional hybrid

Prerequisites

This command requires the meta-convert-dev skill to be available. Read it first to understand the foundational patterns.

Workflow

Step 0: Check for Existing Skill

Before creating a new skill, check if one already exists:

bash
# Check if skill directory exists
ls components/skills/convert-$1-$2/

# Search for existing PRs
gh pr list --search "convert-$1-$2" --state all

If the skill already exists:

  1. Confirm with user: "A convert-$1-$2 skill already exists. Options:"

    • Update mode: Improve the existing skill (add missing sections, enhance examples)
    • Skip: Move on to next task
    • Force create: Replace existing (requires explicit confirmation)

  2. For update mode, skip to Step 6: Populate Content and focus on:

    • Filling gaps identified in validation
    • Adding missing type mappings
    • Improving examples
    • Updating cross-references

  3. Report findings even if skipping:

    markdown
    ## Existing Skill Found

| Field | Value |
|-------|-------|
| Skill | `convert-$1-$2` |
| Status | Already exists |
| Location | `components/skills/convert-$1-$2/SKILL.md` |
| PR | #XXX (if known) |

**Recommendation:** [Update / Skip / Review]

Step 0.5: Check for Reverse Skill

Check if a skill for the reverse direction (convert-$2-$1) already exists:

bash
# Check if reverse skill exists
ls components/skills/convert-$2-$1/

# Search for reverse skill PRs
gh pr list --search "convert-$2-$1" --state all

Why check the reverse skill:

  • Bidirectional insights improve both skills
  • Shared pitfalls and edge cases
  • Consistent terminology and examples
  • Cross-referencing opportunities

If reverse skill EXISTS:

  1. Read it for context - Note patterns that apply in both directions
  2. Reference shared challenges - Type mappings often have bidirectional insights
  3. Document cross-references - Add "See Also" links in both skills
  4. Identify asymmetries - Some patterns only matter in one direction
markdown
## Reverse Skill Found

| Field | Value |
|-------|-------|
| Reverse Skill | `convert-$2-$1` |
| Location | `components/skills/convert-$2-$1/SKILL.md` |
| Key Insights | [List patterns that apply bidirectionally] |

**Action**: Reference in "See Also" section, share pitfalls documentation

If reverse skill DOES NOT exist:

  1. Note it as future work - Add to "See Also" as convert-$2-$1 (not yet available)
  2. Consider creating an issue - If the reverse direction is commonly needed
  3. Document one-way patterns - Some translations are inherently one-directional
markdown
## Reverse Skill Status

No `convert-$2-$1` skill exists. Consider:
- [ ] Create issue for reverse skill if commonly needed
- [ ] Document one-way patterns in this skill's pitfalls section

Step 1: Validate Arguments

  1. Confirm both source and target languages are provided
  2. Validate language names are lowercase and recognized
  3. Construct skill name: convert-$1-$2

If arguments are missing, ask the user:

Please provide source and target languages:
/create-lang-conversion-skill <source-lang> <target-lang>

Example: /create-lang-conversion-skill typescript rust

Step 2: Read Foundation & Reference Skills

Read these skills to understand patterns and gather examples:

  1. Meta-skill (required): components/skills/meta-convert-dev/SKILL.md

    • APTV workflow (Analyze → Plan → Transform → Validate)
    • Type mapping strategies
    • Idiom translation approaches
    • Testing strategies

  2. Existing conversion skills (required - read at least 1):

    • Search for convert-* skills in components/skills/
    • Read one complete skill (e.g., convert-typescript-rust/SKILL.md lines 1-300) to understand:
      • Expected depth for type mapping tables
      • "Why this translation" explanation style
      • Example complexity progression
    • Borrow patterns that apply to your language pair

  3. Language skills (if available):

    • lang-$1-dev - Source language patterns
    • lang-$2-dev - Target language patterns

Before proceeding: Confirm you have read at least one complete conversion skill as a reference.

Step 2.5: Validate 8 Pillars Coverage (Automated)

Before creating a conversion skill, validate that both source and target language skills have adequate coverage of the 8 Pillars essential for code conversion.

Pillar Reference

Pillar Search Terms Why Essential
Module ## Module, import, export, visibility Import/export translation
Error ## Error, Result, Exception, try/catch Error model translation
Concurrency ## Concurrency, async, await, thread Async pattern translation
Metaprogramming ## Metaprogramming, decorator, macro, annotation Attribute translation
Zero/Default ## Zero, ## Default, null, Option, None Null-safety translation
Serialization ## Serialization, JSON, serde, marshal Data structure translation
Build ## Build, ## Dependencies, Cargo, package.json Project migration
Testing ## Testing, #[test], describe, unittest Test suite conversion

Optional 9th Pillar (for REPL-centric languages):

Pillar Search Terms Why Essential
Dev Workflow ## REPL, ## Workflow, interactive, hot reload Development style translation

Include this pillar when either source OR target language is REPL-centric:

Language REPL Type Include 9th Pillar?
Clojure Core development workflow Always
Elixir IEx, LiveView hot reload Always
Erlang Erl shell, hot code loading Always
Haskell GHCi for prototyping Yes
Lisp/Scheme REPL-first development Always
Scala Ammonite, sbt console Yes (optional)
Python IPython, Jupyter Yes (optional)
F# FSI (F# Interactive) Yes (optional)

Why this matters: When converting FROM a REPL-centric language (e.g., Clojure→Rust), developers lose their REPL workflow. The skill should document how to achieve similar rapid feedback loops in the target (e.g., cargo watch, rust-analyzer). When converting TO a REPL-centric language, developers gain new workflows they should leverage.

Automated Validation

Run this validation automatically when reading the lang-*-dev skills:

bash
# Check for section headers (example for bash, but do this by reading the file)
for pillar in "Module" "Error" "Concurrency" "Metaprogramming" "Zero\|Default" "Serialization" "Build" "Testing"; do
  grep -c "## .*$pillar" components/skills/lang-$1-dev/SKILL.md
done

While reading each skill file, check for these patterns:

Pillar ✓ Criteria ~ Criteria ✗ Criteria
Module Has ## Module section with 50+ lines Mentioned in another section No coverage
Error Has ## Error section with examples Has Result/Exception mentions No coverage
Concurrency Has ## Concurrency section Has async/thread mentions No coverage
Metaprogramming Has ## Metaprogramming section Has decorator/macro mentions No coverage
Zero/Default Has dedicated section or table Mentioned in types section No coverage
Serialization Has ## Serialization section Has JSON/serde mentions No coverage
Build Has ## Build section Has package manager mentions No coverage
Testing Has ## Testing section Has test framework mentions No coverage

Quick Score Calculation

Count section headers matching pillars:

  • 8/8: Excellent - proceed confidently
  • 6-7/8: Good - note gaps, proceed with pattern skill references
  • 4-5/8: Fair - strongly recommend improving lang skills first
  • 0-3/8: Poor - must improve lang skills before proceeding

Handling Gaps

Score Action
6-8/8 Proceed. Reference pattern skills for missing pillars
4-5/8 Ask user: Proceed with gaps documented OR improve skills first
0-3/8 Stop. Create issues to improve lang-*-dev skills first

Pattern skill supplements:

  • patterns-concurrency-dev → Concurrency gaps
  • patterns-serialization-dev → Serialization gaps
  • patterns-metaprogramming-dev → Metaprogramming gaps

Pillar Gap Mitigation Examples:

Gap Scenario Mitigation Strategy Example
Source lacks Metaprogramming Research source language decorators/macros Python→Rust: Research @decorator → #[derive()] mapping
Target lacks Concurrency docs Reference pattern skill + web search TypeScript→Go: Use patterns-concurrency-dev for goroutine patterns
Both lack Serialization Create mappings from official docs Clojure→Elixir: Map clojure.data.json → Jason from library docs
Source has partial Error section Supplement with language reference Haskell→Rust: Expand Maybe/Either → Option/Result from Haskell wiki

Concrete mitigation workflow:

  1. Identify specific gap (e.g., "lang-clojure-dev has no Metaprogramming section")
  2. Document what's missing ("macro hygiene, reader macros, syntax-quote")
  3. Find authoritative source (Clojure.org docs, "Clojure for the Brave and True")
  4. Create skill content with attribution in Limitations section
  5. Track as improvement issue for lang-*-dev skill

Report Format

markdown
## 8 Pillars Validation

| Skill | Mod | Err | Conc | Meta | Zero | Ser | Build | Test | Score |
|-------|-----|-----|------|------|------|-----|-------|------|-------|
| lang-$1-dev | ✓ | ✓ | ✓ | ~ | ✓ | ✓ | ✓ | ✓ | 7.5/8 |
| lang-$2-dev | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 8/8 |

**Combined Score:** 15.5/16 (Excellent)
**Gaps:** lang-$1-dev metaprogramming is partial
**Mitigation:** Reference `patterns-metaprogramming-dev`
**Decision:** Proceed ✓

Step 3: Research Language Pair

Before creating the skill, research the specific language pair using these structured checklists:

3.1 Type System Differences

  • Read primitive types sections in both lang skills
  • Create draft mapping table for primitives
  • Identify types without direct equivalents
  • Note numeric precision differences (32-bit vs 64-bit, overflow behavior)

3.2 Error Handling

  • Identify error model in source (Exceptions? Result types? Error returns?)
  • Identify error model in target
  • Map error propagation patterns (try/catch → ?, throw → return Err)
  • Note any "no runtime errors" guarantees (like Elm)

3.3 Concurrency Models

  • Identify async model in source (async/await, callbacks, actors?)
  • Identify async model in target
  • Map concurrency primitives (Promise → Future, Channel → mpsc)
  • Note architectural differences (managed runtime vs explicit)

3.4 Memory Models

  • Source memory model: GC / ownership / manual / managed
  • Target memory model
  • If different, plan ownership translation strategy
  • Note lifetime considerations if applicable

3.5 Idiomatic Patterns

  • What's considered "the way" in source language?
  • What's considered "the way" in target language?
  • Identify patterns that should NOT be directly translated
  • Note paradigm shifts (OOP → FP, imperative → declarative)

3.6 Ecosystem Equivalents

  • Common HTTP libraries
  • JSON/serialization libraries
  • Testing frameworks
  • Build tools

3.7 Paradigm Shifts (if applicable)

  • OOP → Functional: class hierarchies → data + functions, inheritance → composition
  • Imperative → Declarative: loops → recursion/map/fold, mutation → immutability
  • Dynamic → Static: duck typing → interfaces/traits, runtime checks → compile-time
  • Script → Compiled: REPL workflow → build cycle, hot reload → recompile
  • Functional → Functional: Different FP dialects have distinct idioms (see below)

Functional→Functional Translation (e.g., Clojure→Elixir, Haskell→Scala):

Even between functional languages, significant translation is needed:

Aspect Variations Example Pairs
Type system Dynamic vs Static, HM vs dependent Clojure (dynamic) → Haskell (static HM)
Immutability Enforced vs Conventional Clojure (enforced) → Scala (conventional)
Laziness Lazy vs Strict Haskell (lazy) → Elixir (strict)
Concurrency Actor vs STM vs CSP Elixir (actors) → Clojure (STM + core.async)
Macro system Hygienic vs Unhygienic Scheme (hygienic) → Clojure (limited hygiene)
Pattern matching Exhaustive vs Partial Haskell (exhaustive) → Elixir (partial ok)
Effects Pure vs Practical Haskell (IO monad) → Elixir (side effects anywhere)

Don't assume functional→functional is simple—document the FP dialect differences.

3.8 Transpilers & Interop Tools

  • Check for existing transpilers between the languages (e.g., Fable.Python, GopherJS)
  • Note FFI/interop capabilities (calling one language from the other)
  • Document bidirectional insights from transpiler implementations

3.9 Platform Ecosystem Differences

Different runtime platforms have distinct conventions and capabilities:

Platform Languages Key Characteristics
.NET/CLR C#, F#, VB.NET Rich stdlib, NuGet, strong async
JVM Java, Kotlin, Scala, Clojure Maven/Gradle, enterprise tooling
BEAM/OTP Erlang, Elixir Actor model, hot reload, supervision
Native Rust, C, C++, Go Direct memory, no GC (Rust/C), system-level
Scripting Python, Ruby, JavaScript Dynamic, REPL-first, rapid prototyping

When converting across platforms:

  • Note stdlib equivalents (collections, IO, networking)
  • Consider runtime semantics (exceptions, threading, memory)
  • Document dependency ecosystem differences (package managers)

When to Use WebSearch

Use WebSearch when:

  • Lang skills lack coverage for a pillar
  • Looking for real-world migration guides
  • Finding common pitfalls others have encountered

Example queries:

  • "<Source> to <Target> migration patterns 2024" - General migration guides
  • "<Source> <pattern> equivalent in <Target>" - Specific pattern translations
  • "Common mistakes converting <Source> to <Target>" - Pitfalls research
  • "<Source> vs <Target> error handling" - Error model comparison

Step 3.5: Assess Language Pair Difficulty

Rate the complexity of the language pair conversion to set expectations and guide depth of documentation.

Difficulty Rating Matrix

Factor Easy (+0) Medium (+1) Hard (+2)
Type System Same (static→static, dynamic→dynamic) Mixed (static↔dynamic) Opposite + complex (HKTs, dependent types)
Paradigm Same (OOP→OOP, FP→FP) Related (OOP→hybrid) Opposite (OOP→pure FP)
Memory Model Same (GC→GC) Different (GC→ref counting) Opposite (GC→ownership)
Concurrency Same model Related (async→async) Different (threads→actors)
Ecosystem Same platform Related (JVM→JVM) Different platform

Scoring

Total Score Difficulty Expected Skill Size Focus Areas
0-2 Easy 200-400 lines Idiom differences, library mapping
3-5 Medium 400-800 lines Type translation, paradigm shifts
6-8 Hard 800-1500 lines All sections, extensive examples
9-10 Expert 1500+ lines Deep architectural guidance, migration strategies

Example Ratings

Pair Type Paradigm Memory Concurrency Platform Total Difficulty
TypeScript→Python +1 +0 +0 +0 +0 1 Easy
Python→Rust +1 +1 +2 +1 +1 6 Hard
Clojure→Elixir +0 +0 +0 +1 +1 2 Easy
TypeScript→Rust +1 +1 +2 +1 +1 6 Hard
Haskell→Rust +1 +1 +2 +1 +1 6 Hard
Java→Kotlin +0 +0 +0 +0 +0 0 Easy
Python→Haskell +2 +2 +0 +1 +1 6 Hard

Report Format

markdown
## Difficulty Assessment

| Factor | Score | Rationale |
|--------|-------|-----------|
| Type System | +X | [e.g., "Dynamic → Static requires type annotation"] |
| Paradigm | +X | [e.g., "OOP → FP requires mental model shift"] |
| Memory | +X | [e.g., "GC → Ownership requires lifetime understanding"] |
| Concurrency | +X | [e.g., "Promises → Actors"] |
| Platform | +X | [e.g., "Node → BEAM"] |
| **Total** | **X** | **[Easy/Medium/Hard/Expert]** |

**Implications:**
- Expected skill size: X lines
- Key focus areas: [List 2-3 main challenges]
- Recommended examples: [Number based on difficulty]

Step 4: Create Skill Directory

bash
mkdir -p components/skills/convert-$1-$2

Step 5: Generate SKILL.md

Create the skill file using the template below.

Important: For code examples, reference existing convert-X-Y skills rather than creating examples from scratch. This ensures consistency and allows users to see real, tested patterns.

markdown
---
name: convert-<source>-<target>
description: Convert <Source> code to idiomatic <Target>. Use when migrating <Source> projects to <Target>, translating <Source> patterns to idiomatic <Target>, or refactoring <Source> codebases. Extends meta-convert-dev with <Source>-to-<Target> specific patterns.
---

# Convert <Source> to <Target>

Convert <Source> code to idiomatic <Target>. This skill extends `meta-convert-dev` with <Source>-to-<Target> specific type mappings, idiom translations, and tooling.

## This Skill Extends

- `meta-convert-dev` - Foundational conversion patterns (APTV workflow, testing strategies)

For general concepts like the Analyze → Plan → Transform → Validate workflow, testing strategies, and common pitfalls, see the meta-skill first.

## This Skill Adds

- **Type mappings**: <Source> types → <Target> types
- **Idiom translations**: <Source> patterns → idiomatic <Target>
- **Error handling**: <Source> error model → <Target> error model
- **Async patterns**: <Source> concurrency → <Target> concurrency
- **[If applicable] Memory/Ownership**: <Source> memory model → <Target>

## This Skill Does NOT Cover

- General conversion methodology - see `meta-convert-dev`
- <Source> language fundamentals - see `lang-<source>-dev`
- <Target> language fundamentals - see `lang-<target>-dev`
- Reverse conversion (<Target> → <Source>) - see `convert-<target>-<source>`

---

## Quick Reference

| <Source> | <Target> | Notes |
|----------|----------|-------|
| ... | ... | ... |

## When Converting Code

1. **Analyze source thoroughly** before writing target
2. **Map types first** - create type equivalence table
3. **Preserve semantics** over syntax similarity
4. **Adopt target idioms** - don't write "<Source> code in <Target> syntax"
5. **Handle edge cases** - null/nil/None, error paths, resource cleanup
6. **Test equivalence** - same inputs → same outputs

---

## Type System Mapping

### Primitive Types

| <Source> | <Target> | Notes |
|----------|----------|-------|
| ... | ... | ... |

### Collection Types

| <Source> | <Target> | Notes |
|----------|----------|-------|
| ... | ... | ... |

### Composite Types

| <Source> | <Target> | Notes |
|----------|----------|-------|
| ... | ... | ... |

---

## Idiom Translation

### Pattern: <Common Pattern Name>

**<Source>:**
```<source-lang>
// Source code example

<Target>:

&lt;target-lang&gt;
// Target code example - idiomatic, not transliterated

Why this translation:

  • Explanation of why this is idiomatic in target language

[Repeat for major patterns...]

Paradigm Translation (if applicable)

Include this section when converting between different paradigms (OOP→FP, imperative→declarative, etc.)

Mental Model Shift: <Source Paradigm> → <Target Paradigm>

<Source> Concept <Target> Approach Key Insight
Class with state Record + module functions Data and behavior separated
Inheritance Composition / Protocols Favor interfaces over hierarchies
Mutable loops Recursion / fold / map Transformation over mutation
Side effects anywhere Pure functions + IO boundary Effects pushed to edges

Concurrency Mental Model

<Source> Model <Target> Model Conceptual Translation
Threads + locks Actors / CSP Shared state → message passing
Callbacks Streams / Channels Inversion of control → data flow
async/await Process mailboxes Promise → lightweight process

Error Handling

<Source> Error Model → <Target> Error Model

[Detailed section on error translation...]

Concurrency Patterns

<Source> Async → <Target> Async

[Detailed section on concurrency translation...]

[If Applicable] Memory & Ownership

<Source> Memory Model → <Target> Memory Model

[Detailed section for GC ↔ ownership conversions...]

Common Pitfalls

  1. <Pitfall 1>: Description and how to avoid
  2. <Pitfall 2>: Description and how to avoid ...

Limitations (if proceeding with Yellow/Red pillar coverage)

Include this section when creating a conversion skill despite incomplete lang-*-dev coverage.

Coverage Gaps

Pillar Source Skill Target Skill Mitigation
<Pillar> ✓/~/✗ ✓/~/✗ External research / pattern skill / documented gap

Known Limitations

  1. <Area>: This skill has limited guidance on because lang--dev lacks coverage
  2. <Area>: Conversion patterns for may be incomplete

External Resources Used

Resource What It Provided Reliability
Official docs patterns High
Community guide examples Medium

Tooling

Tool Purpose Notes
... ... ...

Examples

Examples should progress in complexity:

Example 1: Simple - <Single concept>

Before (<Source>):

&lt;source-lang&gt;
// Simple, focused example demonstrating one concept

After (<Target>):

&lt;target-lang&gt;
// Idiomatic translation of the single concept

Example 2: Medium - <Multiple concepts>

Before (<Source>):

&lt;source-lang&gt;
// Example combining 2-3 concepts (e.g., types + error handling)

After (<Target>):

&lt;target-lang&gt;
// Shows how concepts interact in target language

Example 3: Complex - <Real-world pattern>

Before (<Source>):

&lt;source-lang&gt;
// Complete, realistic source code (~50-100 lines)
// Demonstrates a real-world use case

After (<Target>):

&lt;target-lang&gt;
// Complete, idiomatic target code
// Shows full translation including edge cases

See Also

For more examples and patterns, see:

  • meta-convert-dev - Foundational patterns with cross-language examples
  • convert-X-Y - Related conversion skills (list specific ones if applicable)
  • lang-<source>-dev - <Source> development patterns
  • lang-<target>-dev - <Target> development patterns

Cross-cutting pattern skills (for areas not fully covered by lang-*-dev):

  • patterns-concurrency-dev - Async, channels, threads across languages
  • patterns-serialization-dev - JSON, validation, struct tags across languages
  • patterns-metaprogramming-dev - Decorators, macros, annotations across languages

### Step 6: Populate Content

Fill in the template with specific content for this language pair:

#### Content Requirements

| Section | Minimum | Quality Bar |
|---------|---------|-------------|
| Quick Reference | 10 entries | Most common type mappings |
| Primitive Types | All primitives | Include edge cases (infinity, NaN) |
| Collection Types | 5+ types | Array, Map, Set, Tuple equivalents |
| Composite Types | 3+ types | Struct, Class, Interface mappings |
| Idiom Translations | See priority list below | Common patterns with "why" explanations |
| Error Handling | Complete section | Full error model translation |
| Concurrency | Complete section | Async/threading translation |
| Memory/Ownership | If applicable | Include if languages differ (GC vs ownership) |
| Examples | 3+ (simple, medium, complex) | Progressive complexity |
| Pitfalls | 5+ pitfalls | Language-pair specific mistakes |

#### Idiom Translation Priority

**Required patterns (must include):**
1. Null/optional handling (null → Option, Maybe → nil, etc.)
2. Collection operations (map, filter, reduce equivalents)
3. Error propagation (try/catch → Result, throws → Either)
4. Async/await patterns (if either language has async)

**Language-specific patterns (include 2-6 based on relevance):**
- Type alias/newtype definitions
- Pattern matching
- Generics/type parameters
- Interface/trait implementations
- Resource cleanup (using/defer/Drop)
- Builder patterns
- Iteration patterns

#### Quality Guidance: Good vs Great

| Aspect | Good | Great |
|--------|------|-------|
| Type mapping | `String → &str` | `String → &str for borrowed, String for owned; use Cow<str> when ownership varies` |
| Why explanation | "Use Result in Rust" | "Use Result because Rust has no exceptions; the ? operator propagates errors like try/catch but at compile time" |
| Example code | Syntactically correct | Syntactically correct + follows target language conventions (naming, formatting, idioms) |
| Pitfall | "Don't forget to handle errors" | "TypeScript's `undefined` vs Rust's `Option`: TS allows property access on undefined (runtime error), Rust requires explicit unwrap (compile error)" |

#### Example Complexity Guide

| Level | Lines | Concepts | Purpose |
|-------|-------|----------|---------|
| Simple | 5-15 | 1 | Demonstrate single type/idiom translation |
| Medium | 20-40 | 2-3 | Show concept interactions |
| Complex | 50-100 | 4+ | Real-world use case, production-ready |

#### Example Quality Checklist

Before finalizing examples, verify each one meets these criteria:

- [ ] **Syntactically valid** - Source code compiles/runs without errors
- [ ] **Target is idiomatic** - Not transliterated (avoid "Source code in Target syntax")
- [ ] **Demonstrates pattern clearly** - Single focus per example (Simple), combined focus (Medium/Complex)
- [ ] **Complexity matches level** - Don't overcomplicate Simple examples
- [ ] **Comments explain "why"** - Not just "what" the code does
- [ ] **Edge cases shown** - Null handling, error paths, empty collections where relevant

#### Testing/Validation Guidance

To verify conversion examples are correct:

1. **Use language playgrounds** for quick validation:
   - TypeScript: [TS Playground](https://www.typescriptlang.org/play)
   - Python: [Python Tutor](https://pythontutor.com/) or REPL
   - Rust: [Rust Playground](https://play.rust-lang.org/)
   - Go: [Go Playground](https://go.dev/play/)
   - Elixir: [Elixir Playground](https://playground.elixir-lang.org/)

2. **For complex examples**, consider:
   - Create minimal test files to verify both source and target compile
   - Run equivalent inputs through both to verify same outputs
   - Check error cases behave equivalently

3. **Document behavioral differences**:
   - If source and target have different semantics (e.g., overflow behavior), note this
   - Include comments like `// Note: Python int is arbitrary precision, Rust i64 overflows`

### Step 7: Validate Skill

Run through this checklist before completing:

#### Structure Validation
- [ ] SKILL.md has valid YAML frontmatter
- [ ] `name` matches directory name (`convert-$1-$2`)
- [ ] `description` includes trigger phrases (convert, migrate, translate)
- [ ] All sections from template are present
- [ ] No placeholder text remains (`...`, `<Description>`, etc.)

#### Content Validation
- [ ] Type mapping tables are comprehensive
- [ ] Idiom translations include "why" explanations
- [ ] Error handling section covers full error model
- [ ] Concurrency section addresses async patterns
- [ ] Memory/Ownership included if languages differ
- [ ] Paradigm Translation included if paradigms differ (OOP→FP, etc.)

#### Type Mapping Validation Checklist
- [ ] **Primitives**: All basic types covered (int, float, string, bool, char)
- [ ] **Numerics**: Precision differences noted (i32 vs i64, overflow behavior)
- [ ] **Nullability**: null/nil/None → Option/Maybe mappings clear
- [ ] **Collections**: Array, List, Map, Set, Tuple equivalents
- [ ] **Composites**: Struct, Class, Interface, Enum, Union mappings
- [ ] **Generics**: Type parameter syntax and constraints
- [ ] **Special types**: Never/Bottom, Unit/Void, Any/Dynamic

#### Example Validation
- [ ] Examples progress in complexity (simple → complex)
- [ ] Source code examples are syntactically correct
- [ ] Target code examples are idiomatic (not transliterated)
- [ ] Examples cover different aspects (types, errors, async)
- [ ] Complex example is realistic and complete

#### Cross-Reference Validation
- [ ] References `meta-convert-dev` as foundation
- [ ] Links to `lang-$1-dev` if it exists
- [ ] Links to `lang-$2-dev` if it exists
- [ ] Mentions reverse skill `convert-$2-$1` in "Does NOT Cover"
- [ ] Lists related `convert-X-Y` skills in "See Also"

### Step 8: Suggest Cross-References

After creating the skill, suggest related skills that should reference it:

```markdown
## Cross-Reference Updates Suggested

Consider adding references to this skill in:

1. **`meta-convert-dev`** - Add to "Existing Conversion Skills" section
2. **`lang-$1-dev`** - Add to "Related Skills" section
3. **`lang-$2-dev`** - Add to "Related Skills" section
4. **`convert-$2-$1`** - Reference as reverse skill (if it exists)

Step 9: Report Results

## Skill Created

| Field | Value |
|-------|-------|
| Skill Name | `convert-<source>-<target>` |
| Location | `components/skills/convert-<source>-<target>/SKILL.md` |
| Extends | `meta-convert-dev` |

**Validation Results:**
- [ ] Structure valid
- [ ] Content complete
- [ ] Examples validated
- [ ] Cross-references added

**Key Features:**
- [List main type mappings covered]
- [List main idiom translations covered]
- [Error handling approach]
- [Concurrency model translation]

**Next Steps:**
1. Review type mapping completeness
2. Test with real conversion scenarios
3. Update cross-referenced skills

Step 10: Self-Review & Feedback

After completing the skill creation, provide feedback on the tools and skills used during the process. This helps improve the ecosystem.

10.1 Identify Skills & Commands Used

List all skills and commands used during this task:

markdown
## Skills & Commands Used

| Resource | Type | How Used |
|----------|------|----------|
| `meta-convert-dev` | skill | Foundation for structure and patterns |
| `lang-$1-dev` | skill | Source language patterns (if used) |
| `lang-$2-dev` | skill | Target language patterns (if used) |
| `convert-X-Y` | skill | Reference for examples (if used) |
| `/create-lang-conversion-skill` | command | This workflow |

10.2 Gather Feedback

For each resource used, evaluate:

What worked well:

  • Clear instructions that helped complete the task
  • Patterns that translated well to this language pair
  • Sections that saved time or prevented mistakes

What could be improved:

  • Missing information that required external research
  • Unclear instructions that caused confusion
  • Patterns that didn't apply to this language pair
  • Suggestions for new sections or examples

Context to include:

  • Which language pair was being created
  • Specific challenges encountered
  • Workarounds used for missing guidance

10.3 Create Feedback Issues

For each resource with actionable feedback:

  1. Search for existing parent issues:

    bash
    gh issue list --repo aRustyDev/ai --search "<skill-or-command-name>" --state open

  2. If parent issue exists (about the skill/command in question):

    • Create a child issue linked to the parent
    • Use Relates to #<parent> in the body

  3. If no relevant parent exists:

    • Create a new issue

Issue Template:

markdown
## Feedback: <skill-or-command-name>

### Context
- **Task**: Creating `convert-$1-$2` skill
- **Used for**: [e.g., "Understanding APTV workflow", "Type mapping patterns"]

### What Worked Well
- [Specific positive feedback with examples]

### Suggested Improvements
- [ ] [Actionable improvement 1]
- [ ] [Actionable improvement 2]

### Additional Notes
[Any other observations or suggestions]

---
Feedback from: `/create-lang-conversion-skill $1 $2`

Example issue creation:

bash
# If parent issue #205 exists for meta-convert-dev
gh issue create --repo aRustyDev/ai \
  --title "feedback(meta-convert-dev): from convert-$1-$2 creation" \
  --body "$(cat <<'EOF'
## Feedback: meta-convert-dev

### Context
- **Task**: Creating `convert-typescript-rust` skill
- **Used for**: Foundation patterns, type mapping strategies

### What Worked Well
- APTV workflow provided clear structure
- Type mapping tables were excellent templates

### Suggested Improvements
- [ ] Add more examples for async cancellation patterns
- [ ] Include guidance on translating decorators/attributes

Relates to #205

---
Feedback from: `/create-lang-conversion-skill typescript rust`
EOF
)"

10.4 Report Feedback Summary

markdown
## Feedback Submitted

| Resource | Issue | Summary |
|----------|-------|---------|
| `meta-convert-dev` | #XXX | [Brief summary] |
| `/create-lang-conversion-skill` | #YYY | [Brief summary] |

Examples

/create-lang-conversion-skill typescript rust
/create-lang-conversion-skill python golang
/create-lang-conversion-skill typescript python

Notes

  • Each conversion skill is ONE-WAY (e.g., convert-ts-rust is different from convert-rust-ts)
  • Always read meta-convert-dev first for foundational patterns
  • Reference existing convert-X-Y skills for structure and examples
  • Focus on idiomatic translations, not syntax transliteration
  • Include comprehensive type mapping tables
  • Provide examples at multiple complexity levels (simple, medium, complex)
  • Complete the validation checklist before marking skill as done
  • Always complete Step 10 - Feedback improves the ecosystem for future skill creation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results