Code Alchemist

Code Alchemist

Turn one developer's repeatable engineering habits into an installable Claude Code Skill.

When to Use

Use this skill when you want to:

• distill coding style: "把张三炼成 skill", "analyze senior-dev's coding style", "preserve someone's habits"
• Generate style guides: Create Author Profile, AGENTS.md snippet, Copilot instructions, or reusable Skill
• Analyze code patterns: Understand how a developer structures code, names variables, handles errors
• Preserve engineering habits: Capture repeatable patterns from an experienced developer
• Create shareable artifacts: Turn personal coding conventions into team standards

Do not use this skill when:

• You just need general code review (no specific author's style to emulate)
• The repository has too few commits from the target author ( "把张三炼成 skill"

> "分析 senior-dev 的代码风格并生成 skill" > "把李四的习惯保存成 skill"

You (Claude) will:

Step 1: Run Analysis

Execute the extraction script automatically:

bash .agents/skills/code-alchemist/scripts/distill_author.sh \
  --repo  \
  --author "" \
  --since "6 months ago" \
  --out /tmp/-analysis

If the user didn't specify a repo, ask for it. If they didn't specify an author, ask for it.

Step 2: Read Analysis Results

Read these files to understand the author's patterns:

• /tmp/-analysis/summary.md - overview
• /tmp/-analysis/summary.json - structured data
• /tmp/-analysis/live_files.txt - files that still exist
• /tmp/-analysis/example_commits.json - sample commits

Step 3: Deep Dive Code Samples

From live_files.txt, read 3-5 representative files based on:

• Top 2-3 most modified files (highest change frequency)
• 1 file from the most active directory
• 1 test file if present in the stats

Look for: naming patterns, import order, state management, error handling, file organization.

Step 4: Generate Output

Based on the user's goal, produce one of the following deliverables (see references/output-contract.md for details):

Option A: Author Profile (style-profile.md)

Use when: User wants a readable style analysis without creating a reusable skill.

Structure:

• Scope (repo, author, time range)
• High-Confidence Rules (evidence-backed patterns)
• Tentative Observations (lower confidence, marked as such)
• Anti-Patterns (what to avoid)
• Evidence Index (traceability to commits/files)

Option B: AGENTS Snippet

Use when: User wants rules added to repository collaboration guidance.

Structure:

• Code Alchemist Author Style Rules
• Naming, Structure, Error handling, Testing conventions
• Anti-patterns

Option C: Copilot Instructions Snippet

Use when: User wants rules added to .github/copilot-instructions.md.

Structure:

• Apply the style in these areas
• Scope, Naming, Module boundaries, Error handling, Testing
• Do not over-apply guidelines

Option D: Reusable Skill (SKILL.md + evals.json) ⭐ Default

Use when: User wants a reusable, installable skill. This is the default when no specific format is requested.

4.1 Determine Installation Preferences

Default behavior (use without asking):

• Location: Current project .agents/skills/
• Name: -style

Only ask the user if they explicitly mention wanting a different location (global) or a custom name. Otherwise, proceed directly with the defaults.

4.2 Create Directory Structure (Staging)

First generate the skill to a staging directory, then install to the target location:

/tmp/-skill/          # Staging directory (temporary)
├── SKILL.md
└── evals/
    └── evals.json

The staging directory allows review before final installation.

4.3 Generate SKILL.md Use this template (adapt content based on analysis):

--- name: description: 'Code like - [brief description of their style]. Use when writing [language/framework] code that should match their conventions in [project type].' ---

# Coding Style

## Naming Conventions

### [Components/Functions/Types]

• [Pattern 1 with example]
• [Pattern 2 with example]

## Code Organization

### Imports

1. [Import order rule]
2. [Import order rule]

### File Structure

• [Rule 1]
• [Rule 2]

## Patterns

### [Category] ``[language] // Example code showing the pattern ``

## Anti-Patterns

• Do not [anti-pattern 1]
• Do not [anti-pattern 2]

## Applicability

Apply to:

• path/pattern/**/*

Do not over-apply to:

• excluded/pattern/**/*

--- Distilled from [N] commits ([+additions]/-[deletions]) in [repo]

4.4 Generate evals.json

Create at least 3 test cases:

{
  "skill_name": "",
  "evals": [
    {
      "id": 1,
      "prompt": "Write a [component type] that [does something] following 's style",
      "expected_output": "Component uses [pattern 1], [pattern 2]",
      "assertions": ["Uses naming convention X", "Follows import order Y"]
    }
  ]
}

4.5 (Optional) Generate README.md

If the user explicitly requests it, create a brief usage guide for the generated skill. Otherwise, skip this step.

Step 5: Install the Skill

Install using the default method (copy) at the default location. Only use symlink if the user explicitly requests it.

Default (复制):

mkdir -p .agents/skills/
cp -r /tmp/-skill/* .agents/skills//

Alternative (软链接) - only if user requests:

mkdir -p $(dirname .agents/skills/)
ln -s /tmp/-skill .agents/skills/

Confirm success with details in user's language:

Chinese: > "已成功将 炼成 skill" > "安装位置: [full-path]" > "安装方式: [复制/软链接]" > "使用: 直接说'使用 风格写代码'"

English: > "Successfully distilled into a skill" > "Installed at: [full-path]" > "Method: [copy/symlink]" > "Usage: Say 'write code in style'"

Manual Workflow (Advanced)

If the user wants more control:

# 1. Run analysis manually
bash .agents/skills/code-alchemist/scripts/distill_author.sh \
  --repo /path/to/repo \
  --author "name" \
  --out ./analysis

# 2. Then ask Claude
"基于 ./analysis 生成 skill"

Analysis Script Options

bash .agents/skills/code-alchemist/scripts/distill_author.sh \
  --repo /path/to/repo \          # Required: target repository
  --author "name|email" \          # Required: author identifier
  --since "6 months ago" \         # Optional: start date
  --until "1 month ago" \          # Optional: end date
  --include "src/**" \             # Optional: include paths (repeatable)
  --exclude "src/generated/**" \   # Optional: exclude paths (repeatable)
  --max-commits 100 \              # Optional: limit commits (default: 100)
  --max-examples 10 \              # Optional: example commits (default: 10)
  --out /path/to/output            # Required: output directory

What Makes a Good Skill

High-Confidence Rules (keep these)

• Naming patterns seen across multiple files
• Consistent import organization
• Repeated architectural patterns
• Stable file structure preferences

Tentative Observations (mark as low confidence)

• Patterns from < 3 files
• One-off naming exceptions
• Experimental code patterns
• Formatting-only changes

Anti-Patterns (explicitly forbid)

• Patterns the author consistently replaces in refactor commits
• Styles seen in old commits but not recent ones
• Copy-pasted patterns from external sources

Troubleshooting

| Issue | Solution | |-------|----------| | No commits found | Check author spelling or try email instead of name | | Analysis too slow | Use --include to narrow to specific directories | | Generated skill doesn't match | Read more sample files from different time periods | | Author uses inconsistent styles | Note this in "Do not over-apply" section |

References

• references/distillation-dimensions.md: 8 dimensions to analyze
• references/output-contract.md: Output format specifications
• Official skill spec: https://agentskills.io/specification

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Fldicoahkiin
• Source: Fldicoahkiin/code-alchemist
• License: MIT

Install and usage instructions live in the source repository linked above.