convez.ai
SkillAutomaçãoIntermediário
tanishq286

tq-forge

tanishq286/tq-forge

Factory autônoma de skills e agents com quality gate determinístico

Ver no GitHub
BomPluginScore · de 0 a 100

Fábrica autônoma que gera skills e agents para Claude Code a partir de uma descrição em uma linha. Cria, avalia com scoring determinístico (0-10) e promove comandos slash e agentes multi-arquivo sem sair do terminal.

Instalação

$npx convez-ai tanishq286/tq-forge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 dias
Versão
v1.2.1
Issues abertas
4
Contribuidores
1

Casos de uso

  • Gerar skills Claude Code sem escrever manualmente
  • Avaliar qualidade estrutural de skills com scoring determinístico
  • Criar agents com arquétipos pré-definidos (pesquisador, coder, analista)
  • Workflow sandbox-to-promote para validação antes da produção

Veredito

tq-forge resolve o problema real de gerar skills Claude Code com qualidade consistente. O quality gate determinístico (scoring 0-10) é o diferencial — nenhum artefato chega à produção abaixo de 7/10. Ferramenta prática para quem quer automatizar workflows repetitivos sem guesswork.

README

A tradução para o português deste README ainda está na fila.

🔨 tq-forge

An autonomous skill + agent factory for Claude Code.

Forge new slash-command skills and multi-file agents from a one-line intent — scored, sandboxed, and promoted into production without leaving your terminal.

npm CI License: MIT Claude Code Skills Shell


What is this?

Claude Code lets you define skills (/your-command) and agents (personas with their own system prompt). Writing good ones by hand is fiddly: you have to remember the file shape, the frontmatter, the section structure, and you have no feedback on whether what you wrote is any good.

tq-forge turns that into a one-liner. You describe what you want; it decides whether you need a skill or an agent, writes it to a sandbox, scores it on structural quality (0–10), and only lets you promote it once it passes. It's a small, opinionated factory for your own Claude Code toolkit.

You:  /tq-forge a skill that summarizes my open GitHub PRs every morning

      → classified: skill
      → slug: github-pr-digest
      → written to ~/.tq-forge/sandbox/forged-skills/github-pr-digest/
      🟢 skill github-pr-digest: 8.5/10 (excellent)
         clarity            9  █████████░
         actionability      9  █████████░
         completeness       9  █████████░
         specificity        7  ███████░░░
      → Next: /tq-forge-promote github-pr-digest

Why you'd want it

  • No more blank-page skill writing. Describe the workflow; get a structured, conventions-following SKILL.md.
  • Quality gate built in. A heuristic scorer checks clarity, actionability, completeness, and specificity. Agents add consistency + handoff clarity. Nothing reaches production below 7/10.
  • Sandbox → promote workflow. Everything starts in ~/.tq-forge/sandbox/. You review and score before a single file touches your live skills dir.
  • Eight agent archetypes. researcher, coder, business-analyst, ops-manager, scraper, reviewer, sales-agent, custom — each with a rigid output format and a {{CONTEXT}} slot for your own domain.
  • Self-curating. /tq-forge-improve rewrites only the weak sections; /tq-forge-scan finds workflows you keep doing by hand that should be skills.

How it compares

Most ways to make a Claude Code skill are either blank-page guesswork or a one-shot LLM generation you can't measure. tq-forge puts a deterministic quality gate between "generated" and "live."

Hand-writingAsk Claude inlinetq-forge
Scaffolds the correct file shape✗partial✓
Scores structural quality (0–10)✗✗✓
Cost to score an artifact—tokens0 tokens (static Python)
Same input → same score—✗✓ deterministic
Sandbox before it touches live skills✗✗✓ mandatory
Re-score gate on promote (≥ 7/10)✗✗✓
Rewrites only the weak sections✗partial✓
Flags workflows you should turn into skills✗✗✓

The thing nothing else here ships is the token-free deterministic scorer: every artifact gets the same 0–10 structural read, every time, for free — and nothing reaches ~/.claude/skills/ until a re-score passes the gate.

It scores structure, not correctness — it catches missing sections and vagueness, not logic bugs. Always read what you promote.

Install

npx tq-forge install

One command. It copies the 13 skills into ~/.claude/skills/, drops the support scripts in ~/.tq-forge/install/, seeds your state home, and checks for bash/python3. Restart Claude Code and you're done.

npx tq-forge doctor      # check the install + deps
npx tq-forge uninstall   # remove skills (keeps your forged data)
/plugin marketplace add tanishq286/tq-forge
/plugin install tq-forge@tq-forge

Restart Claude Code (or reload skills) and verify with /tq-forge-status.

Requirements: Claude Code, bash, and python3 (standard library only — no pip installs). Skills work identically whether installed via npm or as a plugin — they resolve their scripts from $CLAUDE_PLUGIN_ROOT when loaded as a plugin, and from ~/.tq-forge/install otherwise.

First-run setup (30 seconds)

Forged agents inject your domain context. Seed it once:

mkdir -p ~/.tq-forge
$EDITOR ~/.tq-forge/context.md   # who you are, what you build, your hard rules

(If you skip this, agents are still generated — just generic. Skills don't need it.)

The 13 commands

CommandWhat it does
/tq-forge <intent>Classify intent → scaffold a skill or agent → score → log
/tq-forge-skill <intent>Force skill mode
/tq-forge-agent <intent>Force agent mode (5-file scaffold)
/tq-forge-promote <slug>Re-score, then copy sandbox → production
/tq-forge-improve <slug>Rewrite only the weak-scoring sections
/tq-forge-improve-allBatch-improve everything below 7/10
/tq-forge-test <slug>Re-score without rewriting
/tq-forge-listInventory of skills + agents with scores
/tq-forge-agentsAgent registry: kind, score, hand-off wiring
/tq-forge-statusForge state, queue depth, halt status
/tq-forge-scanDetect coverage gaps in your skill library
/tq-forge-queueView / manage deferred work
/tq-forge-resumeClear the pause flag and drain the queue

How it works

  /tq-forge "intent"
        │
        ▼
   ┌─────────┐   classify    ┌──────────────┐
   │ intent  │ ────────────▶ │ skill | agent │
   └─────────┘               └──────┬────────┘
                                    │ scaffold
                                    ▼
                    ~/.tq-forge/sandbox/forged-{skills,agents}/<slug>/
                                    │ quality-score.sh + dry-test.sh
                                    ▼
                            ┌───────────────┐
                            │ score ≥ 7 ?   │
                            └──┬────────┬───┘
                          yes │        │ no
                              ▼        ▼
                  /tq-forge-promote   /tq-forge-improve (1 targeted pass)
                              │
                              ▼
                   ~/.claude/skills/<slug>/   ← live

Sandbox is mandatory. The only path that writes into your live skills dir is /tq-forge-promote, and it re-scores first — so a stale score can never sneak a weak artifact into production.

📖 Full architecture, scoring model, and file layout: docs/HOW_IT_WORKS.md. See real generated output in examples/ — a forged skill (github-pr-digest) and a forged 5-file agent (vendor-vetting).

The scorer

scripts/quality-score.sh is a static, token-free heuristic (pure Python stdlib). It never makes an LLM call, so scoring is free and deterministic.

DimensionSkillsAgentsChecks
clarity✓✓"When to use" is concrete and ≤ ~3 sentences
actionability✓✓Numbered steps with copy-pasteable commands
completeness✓✓Pitfalls + Verification + Tags present
specificity✓✓Real paths/tools, not "do the thing"
consistency✓Output format is a defined, rigid schema
handoff_clarity✓hand_off_to names targets + conditions

scripts/dry-test.sh adds structural validation (frontmatter, the 5 agent files, valid tools.json, word-count bounds).

Use the scorer on its own

The scorer doesn't need the forge. Point it at anything shaped like a skill — including in CI, where it's free because it never calls an API:

bash ~/.tq-forge/install/scripts/quality-score.sh ~/.claude/skills/<your-skill>
bash scripts/quality-score.sh --json <path>     # machine-readable, for pipelines

tq-forge's own CI does exactly this: every push re-scores the bundled skills and fails the build below 7/10.

Configuration

Env varDefaultPurpose
TQ_FORGE_HOME~/.tq-forgeState home: sandbox, logs, queue, your context.md
CLAUDE_SKILLS_DIR~/.claude/skillsWhere /tq-forge-promote installs

State layout:

~/.tq-forge/
├── context.md                    # your domain context (injected into agents)
├── skill-log.json                # inventory of everything forged
├── forge-queue.json              # deferred intents + needs_manual_review
├── halt.flag                     # touch to pause; remove to resume
└── sandbox/
    ├── forged-skills/<slug>/SKILL.md
    └── forged-agents/<slug>/{AGENT.md, system-prompt.md, tools.json, ...}

Pause / resume

touch ~/.tq-forge/halt.flag pauses all forge work — new intents queue instead of running. /tq-forge-resume clears the flag and drains the queue. Handy when you want to batch up requests and run them deliberately.

FAQ

Does scoring cost tokens? No. The scorer is static Python — zero API calls.

Will it overwrite my existing skills? No. Promote refuses on slug collisions and never writes outside CLAUDE_SKILLS_DIR. The sandbox copy stays as a rollback.

Can I edit a forged skill by hand? Yes — then /tq-forge-test <slug> to re-score it.

Is the scorer the final word on quality? It's a structural floor, not a ceiling. It catches missing sections and vagueness; it can't judge whether your procedure is correct. Always read what you promote.

Star this repo

If tq-forge saves you from hand-writing even one skill, a ⭐ helps the next person find it — and tells me which heuristics to sharpen next. That's the whole ask: no newsletter, no account, no telemetry.

Contributing

Issues and PRs welcome — new agent archetypes, smarter scoring heuristics, and example skills especially. See CONTRIBUTING.md.

License

MIT © tanishq286

Ver o original no GitHub

Bom para

Relacionados