Metadata-Version: 2.4
Name: skillgen-ai
Version: 0.3.2
Summary: Analyze any codebase and auto-generate AI agent skill files for Claude Code, Cursor, and other AI tools
Project-URL: Homepage, https://github.com/mmoselhy/skillgen
Project-URL: Repository, https://github.com/mmoselhy/skillgen
Project-URL: Issues, https://github.com/mmoselhy/skillgen/issues
Project-URL: Documentation, https://github.com/mmoselhy/skillgen#readme
Author-email: mmoselhy <mmoselhy07@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,claude-code,code-analysis,cursor,developer-tools,llm-tools,skillgen
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic>=0.20.0; extra == 'llm'
Requires-Dist: openai>=1.10.0; extra == 'llm'
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter-cpp>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-go>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-java>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-python>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-rust>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == 'tree-sitter'
Requires-Dist: tree-sitter>=0.23.0; extra == 'tree-sitter'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">skillgen</h1>
  <p align="center">
    Teach AI assistants your codebase conventions — automatically.
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/skillgen-ai/"><img src="https://img.shields.io/pypi/v/skillgen-ai?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://github.com/mmoselhy/skillgen/actions"><img src="https://img.shields.io/github/actions/workflow/status/mmoselhy/skillgen/ci.yml?branch=main&label=CI" alt="CI"></a>
  <a href="https://github.com/mmoselhy/skillgen/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mmoselhy/skillgen?color=green" alt="MIT License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/pypi/pyversions/skillgen-ai" alt="Python 3.11+"></a>
</p>

<p align="center">
  <b>One command. Your conventions. Every AI tool on your team.</b>
</p>

---

## The Problem

Every time an AI assistant touches your code, it guesses at your conventions. Wrong quote style. Wrong test patterns. Wrong import order. You fix it, it forgets, you fix it again.

**skillgen** reads your actual codebase and generates convention files that Claude Code, Cursor, and other AI tools understand natively. No hand-writing rules. No guessing. Every line is backed by evidence from your code.

---

## Install in Claude Code

```
/plugin marketplace add mmoselhy/skillgen
/plugin install skillgen@skillgen-marketplace
```

That's it. Now you have two slash commands in every project:

```
/skillgen:skillgen              Analyze codebase, generate .claude/skills/*.md
/skillgen:skillgen enrich       Find community skills for your stack
```

> **No Python or pip required.** The plugin runs entirely inside Claude Code — Claude reads your code and generates skill files directly. For even better results, also install the CLI (`pip install skillgen-ai`) to enable **hybrid mode** (CLI stats + Claude semantics).

---

## Install as CLI

```bash
pip install skillgen-ai
skillgen .
```

Generates `.claude/skills/`, `.cursor/rules/`, and `AGENTS.md`. Deterministic output, works offline, runs in CI.

Optional extras:

```bash
pip install skillgen-ai[tree-sitter]  # AST-based analysis (more accurate)
pip install skillgen-ai[llm]          # LLM-enhanced output (requires API key)
```

Requires Python 3.11+.

---

## What It Produces

skillgen scans your code and generates **8 convention categories**:

| Category | What It Captures |
|---|---|
| **Naming** | `snake_case` vs `camelCase`, class suffixes, file naming patterns |
| **Error Handling** | Exception hierarchy, try/except patterns, error propagation style |
| **Testing** | Framework, fixtures, assertion style, mocking patterns |
| **Imports** | Absolute vs relative, grouping order, key dependencies |
| **Documentation** | Docstring format, coverage %, type annotation usage |
| **Architecture** | Directory layout, layering, where new code goes |
| **Code Style** | Line length, quotes, trailing commas, formatter config |
| **Logging** | Library, logger init pattern, structured vs unstructured |

Every bullet includes **prevalence stats** ("82% of files use snake_case") and **real examples** from your code. No generic advice.

## Demo

```
$ skillgen . --dry-run --format claude

 Scanning files and detecting languages...  0:00
 Analyzing patterns...                      0:00
 Synthesizing conventions...                0:00
 Generating skills...                       0:00

--- naming-conventions (dry run, not written) ---
# Naming Conventions

## Function Naming
- **82% Functions use snake_case** (14/17 files)
  - Examples: `analyze_project`, `detect_project`, `validate_input`

## Class Naming
- **41% Classes/types use PascalCase** (7/17 files)
  - Examples: `Language`, `PatternCategory`, `OutputFormat`

--- code-style (dry run, not written) ---
# Code Style

## Formatters & Linters
- **ruff** -- line-length: 100, select: E, F, W, I, N, UP, B, SIM, RUF
- **mypy** -- python_version: 3.11, strict: true

Done! 8 files would be generated.
```

## CLI vs Plugin

| | CLI | `/skillgen` Plugin |
|---|---|---|
| **Install** | `pip install skillgen-ai` | `/plugin install skillgen@skillgen-marketplace` |
| **How it works** | Regex + tree-sitter AST | Claude reads your code |
| **Output style** | Statistical ("82% snake_case") | Semantic ("verb_noun pattern: `get_user`") |
| **Formats** | `.claude/` + `.cursor/` + `AGENTS.md` | `.claude/` only |
| **Speed** | < 1 second | 5-15 seconds |
| **Deterministic** | Yes | No (richer, but varies) |
| **Context cost** | Zero | ~1,700 lines (hybrid) / ~10K (standalone) |
| **Best for** | Teams, CI, multi-format | Individual devs, quick setup |

**Hybrid mode**: When both are installed, `/skillgen` uses CLI stats as the backbone and Claude adds semantic enrichment — best of both worlds.

## Output Formats

**Claude Code** `.claude/skills/*.md` — one file per category:

```markdown
<!-- Generated by skillgen v0.3.0. Do not edit manually. -->
# Code Style
## Quote Style
- **88% Prefers double quotes** (15/17 files)
## Formatters & Linters
- **ruff** -- line-length: 100, select: E, F, W, I, N, UP, B, SIM, RUF
- **mypy** -- python_version: 3.11, strict: true
```

**Cursor** `.cursor/rules/*.mdc` — same conventions, Cursor-native frontmatter.

**AGENTS.md** — single Markdown file at repo root. Uses `<!-- skillgen:start/end -->` markers so your handwritten sections are preserved.

## Community Skills

After generating local conventions, pull in community-curated skills for your stack:

```bash
$ skillgen . --enrich

Found 3 community skills for Python + FastAPI:

  #  Skill                   Description
  1  FastAPI Conventions      Router patterns, DI, HTTPException
  2  Pytest Best Practices    Fixtures, parametrize, conftest
  3  SQLAlchemy Patterns      Session management, eager loading

  Skipped (already covered locally): naming, code-style, imports

$ skillgen . --enrich --apply --pick 1,2
```

207 community skills across Python, TypeScript, JavaScript, Go, Rust, and Java — sourced from Anthropic, GitHub Copilot, and awesome-cursorrules with trust tiers (`official`, `community`, `contributed`).

## Supported Languages

| Language | Frameworks Auto-Detected |
|---|---|
| Python | Django, FastAPI, Flask |
| TypeScript | Next.js, React, Angular, Vue |
| JavaScript | Express, React, Vue |
| Go | Gin, Cobra |
| Rust | Actix, Tokio |
| Java | Spring |
| C++ | — |

skillgen reads your tool configs (ruff, prettier, eslint, mypy, golangci-lint) and embeds the actual settings in generated skills.

## How It Works

```
path ──> DETECT ──> ANALYZE ──> SYNTHESIZE ──> GENERATE ──> WRITE
          |          |            |               |            |
       languages   patterns    conventions     skills       files
       frameworks  evidence    prevalence      confidence   .claude/
                   per-file    config values   meters       .cursor/
```

1. **Detect** — scan file tree, read manifests, identify languages + frameworks
2. **Analyze** — sample up to 50 files/language, extract patterns across 8 categories
3. **Synthesize** — deduplicate, compute prevalence, parse config files
4. **Generate** — render evidence-only skills with confidence scoring
5. **Write** — atomic writes, orphan cleanup, `--dry-run` support

## CLI Reference

```
skillgen <path> [flags]

Output:
  --format, -f <claude|cursor|all>   Target format (default: all)
  --diff                             Show what AI learns vs blank slate
  --dry-run                          Preview without writing files
  --json                             Export analysis as JSON
  --verbose, -v                      Detailed analysis output
  --quiet, -q                        Errors only

Analysis:
  --no-tree-sitter                   Disable AST parsing, use regex
  --llm                              Enhance with Claude/GPT-4o
  --llm-provider <anthropic|openai>  Choose LLM provider

Community:
  --enrich                           Find matching community skills
  --enrich --apply                   Download and install them
  --enrich --apply --pick 1,3        Cherry-pick by number
  --trust <official|community|all>   Filter by trust tier
  --no-cache                         Force re-fetch of skill index
```

## Contributing

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## License

[MIT](LICENSE)
