gitpack

Files (7)

• SKILL.md
• hooks.json
• gitpack.py · scripts/
• gitpack_structured.py · scripts/
• gitpack_toc.py · scripts/
• test_gitpack.py · scripts/
• test_gitpack_deps.py · scripts/

SKILL.md (first lines)

# /gitpack - LLM-Ready Code & Markdown Packer

Pack a codebase **or markdown tree** — or a scattered set of files (e.g. a skill whose command lives in `commands/` and agents in `agents/`) — into a compact context file using only Python's stdlib (AST parsing for Python, regex signatures for other languages, heading+frontmatter extraction for Markdown, direct file reads for the appendix). No external AI tools, no corruption, deterministic output.

## What This Does

Takes one or more input paths (files and/or directories) and produces two output files:
- **`<name>_sig.md`** — SIGNATURE TOC + DIRECTORY/FILE INDEX (compact, scannable)
- **`<name>_full.md`** — same + APPENDIX with full source code read directly from disk

Python signatures are extracted via `ast`; other languages via language-specific regex schemas; **markdown** via headings (`#`-`######`) + YAML frontmatter keys + list items. All exact, deterministic, no LLM involvement.

## Workflow

```
python "<skill-dir>/scripts/gitpack.py" <path>... [--skill <name>] [--name <pack-name>] [--exclude <patterns>] [--overview] [--no-deps]
```

- `<path>...` — one or more files or directories. A directory is **recursed fully** (all nested subdirectories, depth-unlimited). A directly-listed file is included regardless of extension. Use multiple paths to pack a skill scattered across `commands/` + `agents/`, or pass one plugin/skill root and let recursion collect the whole tree.
- `--skill <name>` — **deterministic skill-name resolution.** Resolves `/improve`, `improve`, or `plugin:improve` to its installed directory (plugin cache first, marketplace source second) and packs it. Also auto-includes **plugin-root companions**: top-level docs (`README.md`, `OUTPUT_SCHEMA.md`, `HOOKS_AVAILABLE.md`, `CLAUDE.md`, `AGENTS.md`, `config.json`, `.mcp.json`) plus sibling `agents/` and `commands/` dirs when the skill is nested under a plugin `<skills/>` root. This closes the under-pack gap for skills whose schema/specialists live at the plugin root (e.g. `improve-partner`). Sibling `skills/`, `hooks/`, `scripts/`, `__lib/` are excluded — pass the plugin root explicitly as a path when implementation files are needed. No-op for self-contained skills. Removes the model's cache-vs-source hand-resolution step — prefer this over guessing paths.
- `--name <pack-name>` — output basename (`<pack-name>_sig.md` / `<pack-name>_full.md`). Defaults to the common-parent directory name.
- `--overview` — emit an `## OVERVIEW (LLM-generated)` placeholder section at the top of both outputs. See "Code vs LLM split" below.
- `--no-deps` — disable dependency-following. By default gitpack closes the file set under (a) Python imports (AST-walked: `import x`, `from .y import z`, `__lib__.shared`) and (b) explicit path references in `.md`/`.json`/`.yaml` (e.g. `${SKILL_ROOT}/scripts/run.py`, `../../__lib__/shared.py`, `skills/go/scripts/orchestrate.py`). Only files that exist on disk, live within the pack root, and pass the exclude filter are added — existence-on-disk is the discriminator that skips stdlib/third-party. Bounded (≤150 added files, ≤10 rounds). Use `--no-deps` for a strict only-what-I-listed pack.

1. **DISCOVER** — Collect files from every input path (files included as-is; directories recursed with component-wise exclusion)
2. **EXTRACT** — Per file: `ast` (Python), language regex (JS/TS/HTML/CSS/SQL/YAML/JSON/PowerShell), or heading+frontmatter (Markdown)
3. **BUILD** — Write two markdown files to `P://.claude/.artifacts/`:
   - `_sig.md` — signatures + indexes only
   - `_full.md` — signatures + indexes + full source appendix

**Default exclusions** — always applied unless user overrides with `--exclude`:
```
__pycache__/,*.pyc,*.pyo,*.so,*.dll,*.exe
.venv/,venv/,env/,site-packages/
.pytest_cache/,.mypy_cache/,.ruff_cache/,.tox/
.git/,.hg/,.svn/
dist/,build/,out/,target/,egg-info/,*.egg-info/
.idea/,.vscode/,.DS_Store,Thumbs.db
.env,.env.*,*.log
```

## Output Files

| File | Contents |
|------|----------|
| `<name>_sig.md` | PACK INFO, HOW TO USE, SIGNATURE TOC, DIRECTORY INDEX, FILE INDEX |
| `<name>_full.md` | All of the above + APPENDIX: FULL IMPLEMENTATIONS (full source from disk) |

**Output location:** `P://.claude/.artifacts/` — always, never inside the target directory.
This prevents polluting source trees (especially skills/plugin cache) with temp files. |

## Reporting (model must do — do not skip)

After the run completes, **always report the full Windows paths** of the produced `_sig.md` and `_full.md` to the user — verbatim from the script's final `ARTIFACT PATHS` banner. Do not paraphrase, abbreviate, or omit. The user cannot open what they cannot point to. If you report anything about the run, the paths are the first thing to surface.

## Code vs LLM split (the design principle)

`gitpack` deliberately separates the two layers of a skill:

- **Deterministic code owns the code-shaped work** — file discovery, recursion, exclusion, signature extraction (AST/regex), appendix reads, path/skill resolution. These are exact, reproducible, and have no judgment component. They live in `gitpack.py` (pure stdlib). The `--skill` resolver is the canonical example: name→path resolution was a model hand-step (error-prone cache-vs-source guessing) and is now one deterministic flag.
- **LLM owns the non-code-shaped work** — orientation, summarization, "what should I read first." Use `--overview`: the script emits a marked `## OVERVIEW (LLM-generated)` placeholder into both outputs. The workflow (you, the model) then fills it via an LLM call (`/ai-cli` or `/ai-api`) — 1–3 sentences on what the pack is, its entry points, and the 2–3 files a reader should open first. The script never calls an LLM; it structures the slot the LLM fills.

Rule of thumb when extending gitpack: if the new step has a single correct answer, it belongs in `gitpack.py` (code). If it has no single correct answer — prose, ranking, judgment — it belongs behind `--overview`-style placeholders the model+LLM fill.

## Features

- **Multi-language** — `ast` for Python; regex signatures for JS/TS/HTML/CSS/SQL/YAML/JSON/PowerShell; **Markdown is first-class** (headings + frontmatter keys extracted as the signature TOC)
- **Multi-path** — pass any mix of files and directories; a scattered skill (command + agents in different dirs) packs into one pair via `--name`
- **Pure stdlib** — no external dependencies
- **No corruption** — source read directly from disk for appendix, no LLM processing
- **Deterministic** — same input always produces same output
- **Type annotations preserved** — return types and arg types shown when present

## Scope and Related Files

**Primary target:** the requested directory. But a complete LLM context often needs related files outside that path.

**Always include when present near the target:**
- Any companion `.py` files referenced by the target (e.g., a service that backs a skill)
- Any `CLAUDE.md`, `AGENTS.md`, or `.mcp.json` in the same tree
- If packing a skill, also pack its backing service, companion scripts, or related config files if they live in `P://tools/`, `P://.claude/`, or other well-known locations

**Rule:** If a file is named in code as a dependency or companion, it belongs in the pack. Err on the side of inclusion.

**Automatic dependency resolution (default ON).** Gitpack closes the file set under Python imports (AST) and explicit path references (markdown/JSON/YAML). It pulls in plugin-level `__lib__` modules a skill imports, sibling modules, scripts referenced by name in docs, and transitive imports of those — bounded to files that exist within the pack root. This automates the "include companion files" rule above without a manual hand-off. Pass `--no-deps` to disable.

## Skill Name Resolution

When the target is a known skill name (e.g., `/git`, `handoff:id`), resolve it to a filesystem path before packing:

**Resolution order:**
1. `P://.claude/skills/<name>/` — local skill directory
2. `P://packages/.claude-marketplace/plugins/<plugin>/skills/<name>/` — marketplace source
3. `C:/Users/brsth/.claude/plugins/cache/local/<plugin>/<version>/skills/<name>/` — installed plugin cache

**Rule:** Skills installed via marketplace are loaded from the **cache on C:**, not from P: source. Always resolve through the cache path when the plugin is installed.

```python
# Skill name resolution helper
SKILL_CACHE_ROOT = Path("C:/Users/brsth/.claude/plugins/cache/local")
MARKETPLACE_ROOT = Path("P://packages/.claude-marketplace/plugins")

def resolve_skill_path(skill_ref: str) -> Path | None:
    """Resolve a skill reference like '/git' or 'handoff:id' to a filesystem path."""
    # Strip leading slash and split on ':' for namespaced skills
    name = skill_ref.lstrip("/").split(":")[0]
    # Check marketplace plugins for matching skill
    for plugin_dir in MARKETPLACE_ROOT.iterdir():
        if not plugin_dir.is_dir():
            continue
        skill_path = plugin_dir / "skills" / name
        if skill_path.exists() and skill_path.is_dir():
            # Check if installed in cache
            cache_root = SKILL_CACHE_ROOT
            for cache_plugin in cache_root.iterdir() if cache_root.exists() else []:
                for version_dir in cache_plugin.iterdir() if cache_plugin.is_dir() else []:
                    installed = version_dir / "skills" / name
                    if installed.exists():
                        return installed
            return skill_path  # fall back to marketplace source

From EndUser123/search-research, MIT.

More from EndUser123/search-research