convez.ai
Skill
socitix

stx-skills

socitix/stx-skills

Ver no GitHub
InicialPluginScore · de 0 a 100

Organization-wide Claude Code skills: /git-checkin and /image-resize, plus a zero-registry npx installer

Instalação

$npx convez-ai socitix/stx-skills

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
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

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

stx-skills

Organization-wide Claude Code and Cursor skills collection — ten slash-commands and ten versioned agent personas that drive feature waves, bug fixes, commits, version bumps, PR merges, documentation, and magazine-quality reports, all built around the worktree model. Install into any project without publishing to npm.

📖 Open the walkthrough → — full doc with diagrams, expandable skill catalog, settings reference.

Current release: v1.11.0 · MIT licensed.


Quick install

Source of truth: everything lives under stx-skills/.claude/skills/ and .claude/agents/ (Claude-native markdown). The installer copies from there — Cursor installs apply transforms at copy time.

Claude Code (default)

# From the GitHub repo — no clone needed
cd ~/projects/my-app
npx github:socitix/stx-skills

# From a local sibling clone
npx ../stx-skills

# From an absolute path
npx /Users/me/projects/stx-skills

# Install into an explicit target
npx ../stx-skills ~/projects/my-app

Cursor IDE

cd ~/projects/my-app
npx github:socitix/stx-skills --cursor
# or from a sibling clone:
npx ../stx-skills --cursor

Writes to .cursor/skills/ and .cursor/agents/ with install-time transforms:

  • .claude/agents/ → .cursor/agents/ in all paths
  • Agent tool → Task tool · AskUserQuestion → AskQuestion
  • Named persona spawns → Task(subagent_type: "stx-analyst") etc.
  • Slash-command skills get disable-model-invocation: true in frontmatter

Both IDEs

npx ../stx-skills --both

Installs Claude-native files to .claude/ and Cursor-transformed files to .cursor/ in one pass.

⚠️ Syntax note. The package path goes right after npx. Do not prefix it with install — npx install ../stx-skills fails with could not determine executable to run because npx treats install as the package name. (npm install is different; that's the npm CLI.) The word install is accepted only after the package spec: npx ../stx-skills install works as a no-op verb.

Re-running the installer refreshes — existing STX skill directories are wiped and replaced with the latest. Non-stx-* agent files in the target are preserved.

Installer options

npx ../stx-skills --cursor                  # Cursor IDE only → .cursor/
npx ../stx-skills --both                    # Claude + Cursor in one command
npx ../stx-skills --link                    # symlink Claude skills (dev mode)
npx ../stx-skills --skill stx-feature       # install only one skill
npx ../stx-skills --list                    # show what's available
npx ../stx-skills --help

Running multi-agent waves in Cursor

The /stx-feature and /stx-fix skills are orchestrator instructions — the main Cursor agent reads the skill and spawns subagents via the Task tool:

PhaseParallel?How
Analyst → Architect → QASequential (3 user gates)One Task per phase
Dev waveUp to 3 parallelMultiple Task calls in one turn when scope_paths don't overlap
Dev ↔ Reviewer ↔ QA loopSequential per taskTask chain per task

Persona contracts live in .cursor/agents/stx-*.md. The orchestrator does not embed them inline — it delegates to named subagent types.

Skill-driven worktree model (not IDE-folder-driven)

STX enforces worktrees in the skill protocol, not by which folder you opened in the IDE:

  1. /stx-feature and /stx-fix run on main, create .claude/worktrees/<name>/, then Step 0.5 / 1.5 cd into it and verify branch ≠ main.
  2. All wave artifacts and code edits happen from that worktree cwd (or absolute paths under it).
  3. Every spawned subagent gets a Worktree preamble with the absolute path.

Cursor caveat: Step 0.5 changes the agent's shell cwd but does not switch the Cursor workspace folder. Cursor's native /worktree command and .cursor/worktrees.json are a separate system — STX does not invoke them. For long UI sessions you may still open the worktree folder manually; for waves, trust Step 0.5 + absolute paths.

Optional hard gate for consuming repos: .cursor/hooks.json denying Write on main (see docs/temp/REQ-worktree-enforcement-and-cursor-integration.md).


Agents (Wave 1 v1.8 → Wave 2 v1.9)

The multi-agent wave (/stx-feature) and the bug-fix loop (/stx-fix) spawn agents from versioned persona files under .claude/agents/ instead of inline prompts in SKILL.md. Ten personas total — the Reviewer is new in v1.9, sitting between Dev hand-back and QA's test rerun:

PersonaRoleConsumed by
stx-analyst.mdDecomposes feature request → Features with acceptance criteria/stx-feature
stx-architect.mdDecomposes Features → tier-tagged Tasks/stx-feature
stx-qa.mdAuthors failing tests, reruns them, only agent that may edit tests/stx-feature, /stx-fix
stx-reviewer.md ★Reads Dev diff between Dev and QA. Emits structured verdict; halt on test-file edit / weakened assertion / SUT mock./stx-feature (new in v1.9)
stx-coder.mdSingle-bug implementer/stx-fix
stx-dev-base.mdUniversal Dev prelude (scope guardrails, hand-back format)/stx-feature
stx-dev-tier-db.mdDB-tier overlay: migrations, RLS, data-protection guards/stx-feature
stx-dev-tier-service.mdService-tier overlay: three-tier pattern, result shapes/stx-feature
stx-dev-tier-api.mdAPI-tier overlay: thin handlers, Zod, auth, idempotency/stx-feature
stx-dev-tier-ui.mdUI-tier overlay: React + Tailwind + shadcn, a11y/stx-feature

See AGENTS.md for the full inventory, frontmatter spec, and versioning policy. Each wave records its persona_versions (including the Reviewer) in wave-state.json for reproducibility. The Reviewer's verdicts are appended to wave-state.json.reviewer_verdicts[] per iteration — the foundation for Wave 3 (execution-feedback loop) metrics.

The installer copies .claude/agents/ alongside .claude/skills/ into every consuming project.


Skill catalog

Every skill is one of three types based on where you run it:

TypeMeaningSkills
main-boundYou're on main and want to start something (skill spawns a worktree)/stx-feature, /stx-fix
worktree-boundYou're in a feature worktree (skill operates on it)/stx-pr-merge, /stx-worktree-report
any-boundRuns anywhere — utilities/stx-checkin, /stx-version-bump, /stx-image, /stx-magazine-report, /stx-help, /stx-help-html

/stx-feature — multi-agent feature wave (main-bound)

Interview → Analyst → Architect → QA → tier-specialized Dev agents. Three approval gates, suspicious-change tracking, iteration caps. Produces requirement-verse.html, architecture-verse.html, qa-verse.html, result.html under docs/waves/<wave-id>/, plus a cross-wave docs/waves/wave-wiki.html index rebuilt at the end of every wave.

/stx-feature                                              # Fully interactive
/stx-feature Admin multi-delete on /dashboard             # Seed the request
/stx-feature --resume wave-admin-multi-delete-7f3a        # (planned)

See .claude/skills/stx-feature/SKILL.md.

/stx-fix — two-agent bug-fix loop (main-bound)

Drives a QA → Coder loop against a reproducible bug. QA writes the failing test first; the Coder makes the smallest change to pass. Coder cannot touch test files — that halts the loop. Iteration cap default 5.

/stx-fix                                       # Interactive
/stx-fix Timer offset wrong after DST          # Pre-supply the title

See .claude/skills/stx-fix/SKILL.md.

/stx-checkin — secure commit + push (any-bound)

Pre-commit security scan, deleted-file confirmation, branch-aware push/PR. Blocks secrets (.env, *.pem, credentials.json, …) and warns on noise (.DS_Store, node_modules/, files >10 MB).

/stx-checkin                       # Interactive
/stx-checkin -m "feat: add login"  # With commit message
/stx-checkin --dry-run             # Preview only
/stx-checkin --skip-push           # Commit without push

See .claude/skills/stx-checkin/SKILL.md.

/stx-pr-merge — commit → version bump → PR → merge → tag → cleanup chain (worktree-bound)

Twelve-step chain with build-validation gates around the merge and an integrated SemVer bump + tag. Halts on any failure for user review. Falls back to gh api -X DELETE …git/refs/heads/<branch> when local-checkout blocks branch deletion.

/stx-pr-merge                                    # Run with chained approval (auto-bump)
/stx-pr-merge --interactive                      # Prompt at each gate
/stx-pr-merge --dry-run                          # Print every command without executing
/stx-pr-merge --pr-title "fix: timer offset"     # Pre-supply the PR title
/stx-pr-merge --bump minor                       # Force a minor bump (else auto)
/stx-pr-merge --no-bump                          # Skip version bump entirely
/stx-pr-merge --no-tag                           # Bump but don't push the vX.Y.Z tag

Pre-flight → commit → version bump (separate chore(release): commit) → push & PR → build #1 → squash-merge → refresh main → tag vX.Y.Z & push tag → build #2 → worktree cleanup → branch delete.

Conservative bump default. feat:/fix:/perf: → patch. feat!: or BREAKING CHANGE: in body → major. Anything else → no bump. minor/major are never inferred — pass --bump minor / --bump major to force, or use /stx-version-bump.

See .claude/skills/stx-pr-merge/SKILL.md.

/stx-version-bump — standalone SemVer bump + release commit + local tag (any-bound)

The bump step from /stx-pr-merge extracted as a thin standalone skill. Bumps package.json (or --version-file), creates a separate chore(release): bump version to X.Y.Z commit, and tags locally as vX.Y.Z. Does not push. Use when you forgot to bump in the last shipped PR, want to override the auto-inference, or are aggregating several feature PRs into a single release commit (the findependence chore(release): bump version to 1.4.0 (#97) pattern).

/stx-version-bump                          # auto-infer from HEAD commit subject
/stx-version-bump minor                    # explicit (positional)
/stx-version-bump major --no-tag           # bump but defer tagging
/stx-version-bump --from-commit HEAD~3     # infer from a different commit
/stx-version-bump --version-file VERSION   # non-Node repo
/stx-version-bump --dry-run                # preview only

Same conservative auto-policy as /stx-pr-merge. Working tree must be clean before invoking (so the release commit contains only the bump). Push when you ship — /stx-pr-merge does that automatically, or run git push --follow-tags by hand.

See .claude/skills/stx-version-bump/SKILL.md.

/stx-worktree-report — single-file worktree HTML report (worktree-bound)

Produces a polished *.html under docs/ documenting a worktree's changes. Same shape every time: stats, status pills, approach trade-off table, two Mermaid diagrams, per-file diffs with informative hunks, test output, deferred caveats.

/stx-worktree-report                                          # cwd, infer everything
/stx-worktree-report --worktree ../feature-branch             # explicit path
/stx-worktree-report --base develop                           # diff base (default: main)
/stx-worktree-report --title "PNG → PDF migration"            # override title

See .claude/skills/stx-worktree-report/SKILL.md.

/stx-magazine-report — magazine-style HTML deliverable from any source (any-bound)

Turns any analytical brief — blood panel, GTM deck, 10-K, interview corpus, renovation plan — into a single self-contained .html file in the visual register of a printed magazine: cover, TL;DR scorecard, finding cards with severity meters, targets table, action cards with pill badges, click-to-expand detail library, donut/bar charts, closing prediction band. Print-friendly, mobile responsive, self-contained.

Ships with four editorial palettes:

StyleRegisterBest for
#1 Navy BlueMcKinsey-meets-MonocleGTM, board reports, investment memos, audits
#2 Veew TealWarmer handbookPlaybooks, onboarding, walkthroughs, customer-facing
#3 Crimson MagazineVogue / Cereal / KinfolkHealth, wellness, travel, food
#4 Surprise meClaude picksAnything that doesn't fit the others
/stx-magazine-report                                                # Fully interactive
/stx-magazine-report --style 2 --locale "Kolkata, India"            # Pre-supply choices
/stx-magazine-report --source ./inputs/q3-portfolio.pdf \
                     --output ./reports/q3-portfolio.html           # Explicit I/O

Writes to the working folder (or topic-named subfolder). Returns the file path + top 3 findings in chat. Never commits.

See .claude/skills/stx-magazine-report/SKILL.md and the reusable prompt template.

/stx-image — AI-context-safe image audit (any-bound)

Reports unused and oversized images with a "why" for each target, then optionally resizes via macOS sips or removes unused. Default mode makes zero changes.

/stx-image                                  # Analyze cwd
/stx-image public/                          # Analyze a subdirectory
/stx-image --apply                          # Resize oversized in-place
/stx-image --apply --delete-unused          # Also remove unreferenced
/stx-image --size-kb 300 --max-dimension 1280   # Tighter thresholds

Thresholds default to 500 KB and 1568 px (Claude Vision's internal cap); logos/icons target 512 px.

See .claude/skills/stx-image/SKILL.md.

/stx-help — terse text-mode reference (any-bound)

Prints every skill grouped by type with one-line descriptions. Ends with a pointer to /stx-help-html for the visual walkthrough.

/stx-help

See .claude/skills/stx-help/SKILL.md.

/stx-help-html — editorial walkthrough (any-bound)

Opens help.html — the full walkthrough doc with diagrams, expandable skill catalog, settings reference, and pending-features backlog. Same content drives the GitHub Pages site (see below).

/stx-help-html

See .claude/skills/stx-help-html/SKILL.md.


GitHub Pages

The walkthrough doc is published as a GitHub Pages site at https://socitix.github.io/stx-skills/ — anyone can browse it without installing the package.

The Pages content is docs/index.html, a synced copy of .claude/skills/stx-help-html/help.html. Pages source is configured as main branch, /docs folder.

Keeping docs in sync: the canonical source is .claude/skills/stx-help-html/help.html (it ships with the skill). npm run build also runs prepare-docs, which copies it to docs/index.html. Edit only the canonical; the build pushes it to docs/.

npm run build           # tsc + copy to docs/index.html
npm run prepare-docs    # just the copy step

Development

npm install
npm run build       # compile TypeScript + sync docs/index.html
npm run watch       # recompile TS on change
npm run clean       # remove dist/

# Smoke test skills
node dist/skills/stx-checkin.js --dry-run
node dist/skills/stx-image.js --help
node dist/skills/stx-worktree-report.js --pretty
node dist/cli/install.js --list

Adding a new skill

  1. Add src/skills/<skill-name>.ts with a #!/usr/bin/env node shebang (only if the skill has a CLI binary).
  2. Create .claude/skills/<skill-name>/SKILL.md with YAML frontmatter (name, description, version, author) and optionally README.md with design notes.
  3. If the skill has a binary, register it in package.json:
    "bin": { "<skill-name>": "./dist/skills/<skill-name>.js" }
    
  4. Document the skill in this README and add a catalog entry in .claude/skills/stx-help-html/help.html.
  5. npm run build to verify it compiles and sync the docs.

The installer auto-discovers every directory under .claude/skills/ — no registration needed there.


File structure

stx-skills/
├── package.json                              # bin: stx-skills + 5 skill binaries + generate-help
├── tsconfig.json
├── src/
│   ├── cli/
│   │   ├── install.ts                        # npx stx-skills entry point
│   │   ├── cursor-transform.ts               # --cursor install-time transforms
│   │   └── generate-help.ts                  # rebuilds help docs from catalog.json
│   ├── lib/
│   │   └── version-bump.ts                   # shared SemVer + Conventional-Commits policy
│   └── skills/
│       ├── stx-checkin.ts
│       ├── stx-pr-merge.ts
│       ├── stx-version-bump.ts
│       ├── stx-image.ts
│       └── stx-worktree-report.ts
├── dist/                                     # gitignored — compiled output
├── index.html                                # GitHub Pages root — generated from help.html
├── AGENTS.md                                 # persona inventory (v1.8+)
├── CLAUDE.md                                 # project rule: catalog.json + SKILL.md in sync
├── .claude/
│   ├── agents/                               # 10 versioned persona files
│   │   ├── stx-analyst.md
│   │   ├── stx-architect.md
│   │   ├── stx-qa.md                        # shared by stx-feature + stx-fix
│   │   ├── stx-reviewer.md                  # new in v1.9 — between Dev and QA
│   │   ├── stx-coder.md
│   │   ├── stx-dev-base.md
│   │   └── stx-dev-tier-{db,service,api,ui}.md
│   └── skills/
│       ├── catalog.schema.json                 ← JSON Schema for catalog.json files
│       ├── stx-feature/        (SKILL.md + catalog.json + templates/)
│       ├── stx-fix/            (SKILL.md + catalog.json + template.md)
│       ├── stx-checkin/        (SKILL.md + catalog.json + README.md)
│       ├── stx-pr-merge/       (SKILL.md + catalog.json + README.md)
│       ├── stx-version-bump/   (SKILL.md + catalog.json)
│       ├── stx-image/          (SKILL.md + catalog.json + README.md)
│       ├── stx-magazine-report/(SKILL.md + catalog.json + README.md + prompt.md)
│       ├── stx-worktree-report/(SKILL.md + catalog.json + template.html)
│       ├── stx-help/           (SKILL.md + catalog.json)              ← BEGIN/END AUTO region
│       └── stx-help-html/      (SKILL.md + catalog.json + help.html)  ← BEGIN/END AUTO region
└── scripts/
    └── install.sh                            # fallback bash installer

License

MIT

Ver o original no GitHub

Bom para

Relacionados