old-craft · 旧手艺

简体中文 | English

old-craft — Look before you forge.

In the age of handcrafted software, we learned a quiet discipline:
study what already stands, then build.

Somewhere between autocomplete and "ship it," that craft went missing.

old-craft is the skill of picking it up again —
search the open wilderness of GitHub, read with respect,
honor licenses, and only then lay your own foundation.

Stop reinventing the wheel. Remember how we used to look first.

Version License: MIT Node

Versions: Skill / npm installer 1.1.0 · optional Python service package 0.1.0

AI one-click setup

Copy the prompt below to your AI agent; it will walk through the full setup:

Set up old-craft completely for me:

1. Check whether the `gh` CLI is installed and logged in. If not, install it (ask me which OS) and run `gh auth login`
2. Clone https://github.com/godboss-lab/old-craft.git
3. Run `node bin/old-craft.js --global` to install the skill at user level
4. Confirm the skill is installed and usable
5. Then run /old-craft for my next project about [describe your project]

Replace [describe your project] with your project description and send it. The agent handles the rest.

What it is

old-craft is an Agent Skill. Before you write code, it searches GitHub for similar projects — reads READMEs, evaluates licenses, ranks a Top 5, and tells you what you can adapt vs what you must build yourself.

Core idea: look before you forge. Measure twice, cut once — for programming.

Good for

  • Greenfield projects from scratch
  • Tech selection and architecture decisions
  • Evaluating third-party libraries/frameworks
  • Modernizing an existing project against open-source peers

Not for

  • Ordinary bug fixes
  • Local refactors, adding tests only, or pure docs/config tweaks

Manual install (without an AI)

1. Configure GitHub access

# Windows
winget install --id GitHub.cli

# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

# Then log in
gh auth login

Verify: gh auth status → you should see ✓ Logged in to github.com.

2. Install the skill

# Clone the repo
git clone https://github.com/godboss-lab/old-craft.git
cd old-craft

# Install skill (user-level, available in all projects)
node bin/old-craft.js --global

Prerequisite: Node.js ≥ 18

Other install modes:

node bin/old-craft.js              # project-level (auto-detect tools)
node bin/old-craft.js --global --uninstall

How to trigger

In your AI agent, run /old-craft. The agent walks six gates in order:

Gate 0: What are you building?  → mode, primary_sort, baseline, search intents
Gate 1: Broad search            → wide then narrow; relax filters if thin
Gate 2a: Shortlist              → metadata-only pick of 10–15 candidates
Gate 3: Read & evaluate         → limited README reads + license policy
Gate 2b: Final rank             → multi-factor score → final Top 5
Gate 4: Deliver                 → scaffold plan or gap matrix

primary_sort controls table row order:

  • stars — stable domains, mature ecosystems (popularity first)
  • updated — crawlers, volatile APIs, fast-moving ecosystems (recency first)

Output examples

new_build mode: scaffold plan

## Recommended Top 5 reference projects

| # | Project | Stars | License | Policy |
|---|---------|-------|---------|--------|
| 1 | owner/repo | 12.3k | MIT | adapt |
| 2 | ... | ... | Apache-2.0 | adapt |
| 3 | ... | ... | GPL-3.0 | do_not_copy |

## Scaffold tree
- pyproject.toml
- src/main.py
- tests/
- README.md

## Implementation order
1. ...
2. ...

existing_project mode: gap matrix

## Gap matrix

| Dimension | Current | External evidence | Gap | Priority | License constraint |
|-----------|---------|-------------------|-----|----------|--------------------|
| CI/CD | none | GitHub Actions widely used | no automated deploy | high | MIT can adapt |
| ... | ... | ... | ... | ... | ... |

Compliance

  • No full-repo clones; short excerpts only
  • do_not_copy (e.g. GPL) must not enter generated code
  • Never echo tokens
  • Offline knowledge marked [UNVERIFIED]; no fabricated stars/license/dates
  • Details: skills/old-craft/references/compliance.md

FAQ

Q: Do I need a GitHub token?
A: No. Anonymous REST works (~60 req/hour). gh auth login raises the limit to ~5000/hour.

Q: Do I need LLM_API_KEY?
A: No for the skill path. Your chat model does the reasoning. Only the optional full-pipeline service needs a key.

Q: Which LLMs are supported?
A: Whatever model your AI agent already uses.

Q: Windows ExecutionPolicy error?
A: In your own PowerShell (admin usually not required for CurrentUser):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q: How is this different from Copilot / Cursor code search?
A: Those generate code. old-craft is a research skill for selection and decisions before you write.

Q: What if GitHub rate-limits me?
A: The skill degrades gracefully — marks [UNVERIFIED] and continues with what it has. Prefer gh auth login for higher limits.

Advanced: Python service

Optional. Most users only need the skill path above.

The Python package under service/ exposes CLI / MCP / REST helpers for automation and CI. Import path: old_craft.

cd service
python -m venv .venv
source .venv/bin/activate         # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# CLI
python -m old_craft.cli_agent auth-status
python -m old_craft.cli_agent search --q "todo api language:python" --sort stars
python -m old_craft.cli_agent readme --repo owner/name
python -m old_craft.cli_agent file --repo owner/name --path LICENSE
python -m old_craft.cli_agent license --spdx MIT

# MCP server
python -m old_craft.mcp.server

# REST API
uvicorn old_craft.main:app --host 127.0.0.1 --port 8787

Config: copy service/.env.example → service/.env. Fill GITHUB_TOKEN / LLM_API_KEY as needed (both optional for basic GitHub helpers).

Prerequisite: Python ≥ 3.11

More detail: service/README.md

License

MIT — see LICENSE.