# Code Alchemist

> Distill developer coding style from git history into Author Profile, AGENTS snippet, Copilot instructions, or reusable Skill. Use when analyzing code patterns, preserving engineering habits, or creating shareable style guides.

- **Type:** Skill
- **Install:** `agentstack add skill-fldicoahkiin-code-alchemist-code-alchemist`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Fldicoahkiin](https://agentstack.voostack.com/s/fldicoahkiin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Fldicoahkiin](https://github.com/Fldicoahkiin)
- **Source:** https://github.com/Fldicoahkiin/code-alchemist/tree/main/.agents/skills/code-alchemist

## Install

```sh
agentstack add skill-fldicoahkiin-code-alchemist-code-alchemist
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
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:

```json
{
  "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 (复制):**
```bash
mkdir -p .agents/skills/
cp -r /tmp/-skill/* .agents/skills//
```

**Alternative (软链接) - only if user requests:**
```bash
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:

```bash
# 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
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](https://github.com/Fldicoahkiin)
- **Source:** [Fldicoahkiin/code-alchemist](https://github.com/Fldicoahkiin/code-alchemist)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fldicoahkiin-code-alchemist-code-alchemist
- Seller: https://agentstack.voostack.com/s/fldicoahkiin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.