convez.ai
SkillProdutividadeAvançado
siege-analytics

Claude Configs Public

siege-analytics/claude-configs-public

Skills reutilizáveis e resolver de padrões para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Repositório de skills reutilizáveis, templates e configurações de inicialização para Claude Code. Inclui um resolver de padrões de tarefas que mapeia ações necessárias para skills específicas, biblioteca de book-skills derivados de obras clássicas (Clean Code, DDIA, Effective Python), e hooks de enforcement que garantem que as skills corretas sejam consultadas antes de qualquer ação significativa.

Instalação

$npx convez-ai siege-analytics/claude-configs-public

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
1
Forks
1
Acompanhando
0
Saúde
62%
Último commit
há 2 dias
Versão
v3.5.101
Issues abertas
222
Contribuidores
4

Casos de uso

  • Padronizar workflows de desenvolvimento em sessões Claude Code
  • Garantir que skills apropriadas sejam consultadas antes de ações críticas
  • Aplicar convenções e regras universais em escrita de código, manipulação de dados e output
  • Inicializar novos projetos com templates e configurações pré-estruturadas
  • Consultar práticas de engenharia derivadas de livros técnicos clássicos

Veredito

Uma arquitetura sofisticada para governança de skills em sessões Claude Code. O resolver é a inovação principal — força pensamento estruturado antes de ação (padrão 'think-first') e injeta contexto relevante automaticamente. Exige disciplina e conhecimento profundo do repositório para extrair máximo valor, mas compensa com consistência e prevenção de erros em workflows complexos.

README

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

Claude Code Configurations (Public)

Reusable Claude Code skills and project initialization templates.

For use with claude_init or standalone. Pin to a release tag -- see Quick Start.

Latest release License: MIT

Contents

PathPurpose
RESOLVER.mdSkill resolver -- master index mapping task patterns to required skills. Mandatory first read before any non-trivial action.
CHANGELOG.mdRelease notes by version.
skills/Categorized reusable skills for Claude Code sessions.
skills/_*-rules.mdAlways-on conventions -- applied across every skill that touches code, data, or output. See Conventions.
skills/shelves/DBrain book-skill library -- book-derived skills (Clean Code, DDIA, Effective Python, etc.) organized into 11 topic shelves. See DBrain.
hooks/Shell hooks (PreToolUse, UserPromptSubmit) that enforce the resolver.
dist/RULES_BUNDLE.mdRules bundle -- concatenation of all always-on rules for non-hook runtimes. See Rules bundle.
dist/RULES_BUNDLE.jsonSame content as JSON for selective injection / staleness hashing.
bin/install.shSingle-command install -- detects Craft Agent, builds, deploys, installs hooks. See Quick Start.
bin/scaffold-project.pyScaffold new project skill directories (in-tree or satellite).
templates/Project templates (CLAUDE.md, settings.local.json).

The Skill Resolver

The problem this repo solves: skills are only useful if they fire before the action they govern. A catalog of skills the agent could consult is worth nothing if the agent doesn't actually read them first.

RESOLVER.md is a task-pattern → required-skill index. When Claude is about to do something (write Delta data, create a PR, author a ticket, run a spatial join), it scans the resolver, finds the matching row, and reads the mapped SKILL.md before acting. If no pattern matches, universal pre-action checks (catalog-first, brain-first, test-before-bulk, ticket-required, etc.) still apply.

The first gate is think. Every catalog-bypass, every premature cutover, every half-designed pipeline the resolver exists to prevent traces back to acting before thinking. The think skill is not one pattern among many -- it is the mandatory first step before any feature, refactor, architecture change, cutover, or >30-minute task. The rest of the resolver assumes think has already fired.

Inspired by GBrain's "thin harness, fat skills" pattern -- intelligence lives in the skills, not the runtime. The resolver is the discovery layer; think is the gate.

Enforcement

Three enforcement layers keep the resolver active:

  1. Session start -- every project CLAUDE.md references RESOLVER.md as the first action of any non-trivial task.
  2. Every user turn -- hooks/resolver/inject-resolver.sh is a UserPromptSubmit hook that injects the resolver summary into active context on every prompt. Context doesn't decay by turn 20.
  3. Pre-tool-use -- hooks/infrastructure/catalog-guard.sh is a PreToolUse hook on Bash that matches dangerous catalog-bypass patterns and blocks them with a STOP-read-skill reminder.

Wire the hooks by merging hooks/settings-snippet.json into ~/.claude/settings.json (or project .claude/settings.local.json), replacing /path/to/claude-configs-public with the actual absolute path to the on-disk hooks/ (typically a workspace path -- see Wire and verify hooks for the rsync-first sequence and the canonical verify-it-fires invocation).

Always-on conventions

Files at the root of skills/ named _*-rules.md are loaded by the resolver Conventions table and apply to every relevant skill. They're the always-on policy layer:

FileScopeUse when
_output-rules.mdCommit trailers, attribution policy, docstring minimums, markdown styleAny skill that writes anything
_data-trust-rules.mdDefault assumption: tabular data lies. Validate at boundariesBefore any spatial / identifier / external-data work
_principles-rules.mdClean Code maxims (naming, function size, error handling)Always-on for any code task
_python-rules.mdEffective Python idiomsTouching *.py
_jvm-rules.mdEffective Java + Effective Kotlin (merged)Touching JVM languages, including Scala on Spark
_typescript-rules.mdEffective TypeScript idiomsTouching *.ts / *.tsx
_rust-rules.mdRust idiomsTouching *.rs
_siege-utilities-rules.mdPrefer siege_utilities for utility-shaped problems before writing a new helper. Consider PRs upstream when the gap is generic.Writing Python utilities
_definition-of-done-rules.mdFive hard criteria for "done": code-reviewed, edge cases explored, tests written, ticket updated, ticket exists.Every behavior change

Rules bundle

The always-on rules reach the agent in hook-capable runtimes (Claude Code CLI) via the resolver injection hook. For runtimes that don't support hooks (Craft Agent, Cursor, Cody), the build emits a rules bundle -- a single file concatenating all _*-rules.md content:

ArtifactFormatUse
dist/RULES_BUNDLE.mdMarkdownMount as a system-prompt addendum
dist/RULES_BUNDLE.jsonJSON with per-rule keysSelective injection, staleness hashing

The bundle includes a version/commit banner and is regenerated on every build from source. bin/install.sh deploys it to the Craft Agent workspace automatically.

Tier A (hook-capable): hooks remain preferred -- they re-inject every turn and handle staleness. The bundle is a fallback.

Tier B (non-hook): mount RULES_BUNDLE.md as a system-prompt addendum via whatever mechanism the runtime provides. The bundle gets the content in front of the agent; it does not provide mechanical enforcement (tool-call blocking), which requires hook support.

Project scaffolding

bin/scaffold-project.py creates project-specific skill directories:

# In-tree project (under projects/ in this repo)
python bin/scaffold-project.py init my-project --repo org/my-repo --owner me@example.com

# Standalone satellite repo (flat-sync pattern)
python bin/scaffold-project.py satellite my-project --repo org/my-repo --owner me@example.com

# Add a skill to an existing project
python bin/scaffold-project.py add-skill my-project my-new-skill

See python bin/scaffold-project.py --help for all options.

Skills

Skills are classified by how they're invoked:

  • Reference -- Knowledge Claude applies automatically when relevant. Not a slash command.
  • Action -- Workflows with side effects. User invokes via /skill-name.
  • Analytical -- Analysis that produces findings. User invokes via /skill-name.
  • Router -- Dispatches to sub-skills based on context. Saves description budget at scale.

Router Skills

Routers cover an entire category with one description slot. Sub-skills are loaded on demand based on file type, imports, or problem signals.

RouterSub-SkillsTriggers On
coding-standardspython, python-patterns, python-exceptions, sql, postgis, spark, scala-on-spark, geopandas, sedona, duckdb-spatial, django, pipeline-jobs, code-review, qml-component-review*.py, *.sql, *.scala, file imports, framework signals
analysis-methodsspatial (router itself; dispatches to per-engine spatial skills)Geographic data, spatial queries; future: statistical, graph, entity-resolution, NLP
shelves (DBrain)11 topic shelves with 53 book skillsEngineering practice / language idioms / business / design questions -- see DBrain

Spatial skills

skills/analysis/spatial/ is itself a router that dispatches to four per-engine skills based on data scale × GDAL availability × workload pattern:

EngineSkillUse when
PostGIScoding/postgis/Persistent multi-user; ACID; rich indexes (GIST/SP-GIST/BRIN). Includes a Mastering PostGIS distillation.
GeoPandascoding/geopandas/Single-node Python, Pandas idiom. Folds raw Shapely. Has explicit no-GDAL fallbacks.
Apache Sedonacoding/sedona/Distributed spatial joins on Spark. Same skill for PySpark and Scala scaffolding. Includes raster.
DuckDB-spatialcoding/duckdb-spatial/SQL on Parquet without server; bundles GEOS/GDAL/PROJ -- the strongest single tool for GDAL-less environments.

Always start spatial work with siege_utilities.geo.capabilities.geo_capabilities() to detect the environment tier, then route from analysis/spatial/SKILL.md.

Action Skills

User-invoked. These change state (git, APIs, tickets, files).

CategorySkillDescription
git-workflow/commitStructured commits with ticket references
git-workflow/branchBranch naming convention (type/descriptive_string)
git-workflow/create-prPull requests with bidirectional ticket linking
git-workflow/mergeDevelop-first merge workflow
git-workflow/develop-guardEnsure develop branch exists
session/wrap-upEnd-of-session commit and documentation cleanup
session/pr-commentsTriage and respond to PR comments
session/coderabbit-responseTriage and respond to CodeRabbit reviews
planning/create-ticketCreate tickets in any platform (GitHub, GitLab, Jira, Linear)
planning/close-ticketClose with summary comment, linked commits, verification
planning/update-ticketAdd progress, link commits, update fields
planning/pre-work-checkClaim ticket → mark in-progress → branch → start (the pre-flight)
maintenance/consolidateFind and consolidate redundant documentation

Analytical Skills

User-invoked. Read-only analysis that produces recommendations.

CategorySkillDescription
coding/code-reviewSystematic review: correctness, security, data integrity, performance
coding/qml-component-reviewQML component decomposition; properties-in / signals-out discipline
planning/im-feeling-luckyPrioritize roadmap items by context, age, dependencies, diversity
thinking/thinkDesign-first gate: structured design before any implementation
meta/check-resolvableAudit that every skill is reachable from RESOLVER

Reference Skills

Auto-applied by Claude when relevant. Not behind a router.

CategorySkillDescription
documentation/cascading-documentationCascading documentation: inline, files, repo, KMS levels
documentation/notion-knowledge-baseNotion knowledge base authoring at 5th-grade reading level
infrastructure/databricksDatabricks workspace, jobs, DLT, Delta, Unity Catalog, Photon
infrastructure/unity-catalogUnity Catalog permissioning specifics
infrastructure/opsShared-infra guardrails (cyberpower UPS, K8s pod limits, Rundeck concurrency)
maintenance/library-api-evolutionRenaming public functions, changing defaults, dropping columns safely

Meta Skills

CategorySkillDescription
meta/skillbuilderCreate, audit, and fix skills per Anthropic's guidelines

Quick Start

One-command install (recommended)

Clone the repo and run the install script. It detects your environment and does the right thing:

git clone https://github.com/siege-analytics/claude-configs-public.git
cd claude-configs-public
bash bin/install.sh

What it does:

  • Craft Agent detected (~/.craft-agent/workspaces/ exists): builds the flat layout + rules bundle, deploys skills/hooks/resolver/bundle to your workspace, installs hook settings, validates the deployment.
  • No Craft Agent: builds both layouts, installs hooks to .claude/settings.local.json for Claude Code CLI.

Options: --workspace <slug> to target a specific workspace (default: my-workspace), --no-craft-agent to force CLI-only mode.

Pin to a release tag

This repo publishes two release-branch artifacts per tag for two consumer runtimes -- see Distribution layouts below for the full explanation.

For Claude Code with the resolver hook (the original target), pull from release/nested:

git subtree add --prefix .claude/skills \
  https://github.com/siege-analytics/claude-configs-public.git release/nested --squash
# Or pin: ...claude-configs-public.git v1.0.0-nested --squash

For Craft Agent (slash-command pane), pull from release/flat:

TMP=$(mktemp -d)
git clone --depth 1 --branch release/flat \
  https://github.com/siege-analytics/claude-configs-public.git "$TMP/repo"
rsync -a "$TMP/repo/skills/" ~/.craft-agent/workspaces/<ws>/skills/
rsync -a "$TMP/repo/hooks/"  ~/.craft-agent/workspaces/<ws>/hooks/
rm -rf "$TMP"

Plain rsync -a (no --delete): preserves any local files in the workspace's skills/ or hooks/ that aren't shipped upstream. The hooks rsync MUST run before wiring ~/.claude/settings.json (next step), because the snippet's command paths reference workspace files that have to exist on disk first.

Wire and verify hooks

After the workspace rsync, merge hooks/settings-snippet.json into ~/.claude/settings.json (back the original up first), replacing every /path/to/claude-configs-public with the actual workspace path (e.g. ~/.craft-agent/workspaces/<ws>).

The snippet ships every hook the repo provides: UserPromptSubmit (resolver injection) and PreToolUse matchers for Bash (catalog-guard, branch-guard, no-attribution, ticket-required, no-sensitive-files, no-broad-staging) and mcp__session__send_agent_message (no-slug-form-outbound parser-drop guard). Adding new hooks upstream means re-rsync + re-merge.

Verify a hook fires after wiring:

# Should print BLOCKED... and exit 2
echo '{"tool_input":{"message":"see [skill:think]"}}' \
  | ~/.craft-agent/workspaces/<ws>/hooks/agent-comms/no-slug-form-outbound.sh
echo "exit=$?"

If exit is 0 instead of 2, the hook is on disk but not executable -- run chmod +x ~/.craft-agent/workspaces/<ws>/hooks/agent-comms/*.sh ~/.craft-agent/workspaces/<ws>/hooks/git/*.sh ~/.craft-agent/workspaces/<ws>/hooks/infrastructure/*.sh ~/.craft-agent/workspaces/<ws>/hooks/resolver/*.sh. If the hook never fires from a real mcp__session__send_agent_message call, settings.json is malformed -- validate with python3 -c 'import json, os; json.load(open(os.path.expanduser("~/.claude/settings.json")))'.

To upgrade later:

git subtree pull --prefix .claude/skills \
  https://github.com/siege-analytics/claude-configs-public.git v0.2.0 --squash

With claude_init

If you use the siege_analytics_zshrc config:

claude_init

This clones skills, generates CLAUDE.md from the template, and copies settings.local.json.

Manual setup (tracking main, no pin)

mkdir -p .claude

git subtree add --prefix .claude/skills \
  https://github.com/siege-analytics/claude-configs-public.git main --squash

curl -o CLAUDE.md \
  https://raw.githubusercontent.com/siege-analytics/claude-configs-public/main/templates/CLAUDE.md.template
# Edit CLAUDE.md and replace {{VARIABLES}}

curl -o .claude/settings.local.json \
  https://raw.githubusercontent.com/siege-analytics/claude-configs-public/main/templates/settings.local.json

Update skills

# Pinned: change tag and re-pull
git subtree pull --prefix .claude/skills \
  https://github.com/siege-analytics/claude-configs-public.git v0.2.0 --squash

# Tracking main: just pull
git subtree pull --prefix .claude/skills \
  https://github.com/siege-analytics/claude-configs-public.git main --squash

Spatial skills (added in v0.2.0)

The spatial skill set is the largest single addition since the initial release. Four per-engine skills + a router + extensive cross-cutting principles. See the Spatial skills section above for the engine table; the router at skills/analysis/spatial/SKILL.md dispatches by data scale × GDAL availability × workload pattern.

Notable distillations and references shipped in v0.2.0:

Template Variables

The CLAUDE.md template supports:

VariableExampleSource
{{PROJECT_NAME}}my-projectDirectory name or git remote
{{ORG_NAME}}siege-analyticsGit remote organization
{{GIT_ROOT}}~/git/siege-analyticsParent directory
{{CURRENT_DATE}}2026-05-02System date

DBrain -- book-skill library

skills/shelves/ is a separate, larger library of book-derived skills -- DBrain, in the spirit of GBrain. It uses the same "thin harness, fat skills" pattern and is gated by the same resolver, but lives under its own meta-router so its description budget cost is one slot per shelf, not one per book.

ShelfTopic
engineering-principles/Clean Code, Clean Architecture, Design Patterns, DDD, Refactoring, Pragmatic Programmer, Ousterhout
systems-architecture/Designing Data-Intensive Applications, System Design, Microservices Patterns, Release It!, HPBN, system-design interview
languages/Effective Python/Java/Kotlin/TypeScript, Kotlin in Action, Spring Boot, Programming Rust, Rust in Action, asyncio, web scraping
data-and-pipelines/Pipeline design and scheduling patterns
product/JTBD, Continuous Discovery, Design Sprint, Lean Startup, Lean UX, Inspired, Mom Test, retention
marketing/CRO, StoryBrand, Contagious, Made to Stick, Scorecard / One-Page Marketing, Hooked
sales/Predictable Revenue, Negotiation, Influence, $100M Offers
strategy/Blue Ocean, Crossing the Chasm, Traction (EOS), Obviously Awesome
design/Refactoring UI, iOS HIG, UX heuristics, web typography, Top, Don't Make Me Think, Microinteractions
team/Drive, the 37signals way
storytelling/Storytelling with Data, Animation at Work

See skills/shelves/SKILL.md (the meta-router) and the per-shelf routers for what each shelf dispatches to.

siege_utilities

Many skills explicitly delegate to siege_utilities when it covers the task. The _siege-utilities-rules.md always-on rule formalizes this preference: before writing a Python utility, helper, or one-off function, check whether siege_utilities already provides it. If it almost solves the problem but doesn't, file an upstream PR before adding a local helper.

The spatial skills in particular (per-engine siege-utilities-<engine>.md references) document what SU obviates and what's still bring-your-own.

Works well with

Definition of Done

Code is not finished until all five criteria pass. This is a gate, not a recommendation, enforced via skills/_definition-of-done-rules.md:

#CriterionOperationalized by
aCode-reviewed/code-review
bEdge cases exploredcode-review §1 (concrete checklist)
cTests writtentests are mandatory; no infrastructure → add it first; PRs without tests must justify
dNon-trivial updates → update the ticket/update-ticket, /close-ticket
eWork has a ticket/pre-work-check

The PR-creation skill (/create-pr) gates on all five before opening; failed criteria → PR opens as draft. The session wrap-up skill (/wrap-up) verifies all five before closing. Soft rules erode -- these are documented responses to specific Siege incidents.

Exempt from (a)–(d) but not (e): typo fixes, doc-only changes, tooling chores. Even exempt changes need a ticket for the audit trail.

Distribution layouts

The same source serves two consumer runtimes via a build step. Pick the layout that matches yours.

LayoutBranch / tagSkills tree shapeConsumer
nestedrelease/nested, vX.Y.Z-nestedSkills under category folders (coding/code-review/, git-workflow/commit/, ...)Claude Code with the resolver hook
flatrelease/flat, vX.Y.Z-flatLeaf skills at skills/<slug>/; routers stay at category rootCraft Agent (slash-command pane)

Both layouts contain identical content; only the file-tree shape differs. The build resolves [skill:slug] and [rule:slug] tokens to layout-appropriate paths so cross-references work in both worlds without manual maintenance.

main is the source of truth (nested layout with tokens). Build outputs are published to release/nested and release/flat by CI on every push to main and every tag. Pin downstream consumers to a release-branch tag (v1.0.0-nested / v1.0.0-flat), not the source tag -- the source has the build infrastructure but tokens are unresolved.

See CONTRIBUTING.md for the slug-token convention, build-script details, and contributor workflow.

Contributing

See CONTRIBUTING.md. Short version: skills cross-reference each other by [skill:slug] token (not file path); the build emits two layouts; CI enforces token form on every PR.

Releases & versioning

Versions follow SemVer. Major version bumps for incompatible discovery / build / token-format changes; minor for additive skills or shelves; patch for fixes inside existing skills.

See CHANGELOG.md for the per-version diff.

Tag scheme. Each source tag (v1.0.0 on main) produces two consumer-facing tags via CI:

  • v1.0.0-nested on the release/nested branch -- pull this for Claude Code with the resolver hook
  • v1.0.0-flat on the release/flat branch -- pull this for Craft Agent

main is the rolling source-of-truth (with build infrastructure and unresolved tokens). Always pin downstream consumers to one of the resolved release-branch tags.

Credits

The DBrain shelves under skills/shelves/ are integrated and adapted from two MIT-licensed upstream skill libraries:

  • ZLStas/skills -- Clean-Code reviewer agents, Effective-* language rules, and skills for Effective Python/Java/Kotlin/TypeScript, Kotlin in Action, Spring Boot, Programming Rust, Rust in Action, asyncio, web scraping, data-pipeline patterns, system-design interview, storytelling, and animation.
  • wondelai/skills -- Deep references/-rich skills covering Clean Code, Clean Architecture, DDD, Refactoring, Pragmatic Programmer, Ousterhout, DDIA, system design, Release It!, HPBN, and the full product / marketing / sales / strategy / design / team shelves.

Inspiration for the shelves model: GBrain.

The PostGIS skill draws on Mastering PostGIS (Witkowski, Chojnacki, Mackiewicz, 2017), Paul Ramsey's blog, PostGIS in Action 3rd ed. (Obe & Hsu, 2021), and Crunchy Data's geospatial materials. See per-skill citations.

See THIRD_PARTY_NOTICES.md for full attribution, commit pins, and per-book source mapping.

License

MIT -- see LICENSE.

Ver o original no GitHub

Bom para

Relacionados