Claude Configs Public
siege-analytics/claude-configs-public
Skills reutilizáveis e resolver de padrões para Claude Code
Ver no GitHubRepositó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-public1 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
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.
Contents
| Path | Purpose |
|---|---|
RESOLVER.md | Skill resolver -- master index mapping task patterns to required skills. Mandatory first read before any non-trivial action. |
CHANGELOG.md | Release notes by version. |
skills/ | Categorized reusable skills for Claude Code sessions. |
skills/_*-rules.md | Always-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.md | Rules bundle -- concatenation of all always-on rules for non-hook runtimes. See Rules bundle. |
dist/RULES_BUNDLE.json | Same content as JSON for selective injection / staleness hashing. |
bin/install.sh | Single-command install -- detects Craft Agent, builds, deploys, installs hooks. See Quick Start. |
bin/scaffold-project.py | Scaffold 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:
- Session start -- every project
CLAUDE.mdreferencesRESOLVER.mdas the first action of any non-trivial task. - Every user turn --
hooks/resolver/inject-resolver.shis aUserPromptSubmithook that injects the resolver summary into active context on every prompt. Context doesn't decay by turn 20. - Pre-tool-use --
hooks/infrastructure/catalog-guard.shis aPreToolUsehook onBashthat 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:
| File | Scope | Use when |
|---|---|---|
_output-rules.md | Commit trailers, attribution policy, docstring minimums, markdown style | Any skill that writes anything |
_data-trust-rules.md | Default assumption: tabular data lies. Validate at boundaries | Before any spatial / identifier / external-data work |
_principles-rules.md | Clean Code maxims (naming, function size, error handling) | Always-on for any code task |
_python-rules.md | Effective Python idioms | Touching *.py |
_jvm-rules.md | Effective Java + Effective Kotlin (merged) | Touching JVM languages, including Scala on Spark |
_typescript-rules.md | Effective TypeScript idioms | Touching *.ts / *.tsx |
_rust-rules.md | Rust idioms | Touching *.rs |
_siege-utilities-rules.md | Prefer 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.md | Five 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:
| Artifact | Format | Use |
|---|---|---|
dist/RULES_BUNDLE.md | Markdown | Mount as a system-prompt addendum |
dist/RULES_BUNDLE.json | JSON with per-rule keys | Selective 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.
| Router | Sub-Skills | Triggers On |
|---|---|---|
| coding-standards | python, 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-methods | spatial (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 skills | Engineering 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:
| Engine | Skill | Use when |
|---|---|---|
| PostGIS | coding/postgis/ | Persistent multi-user; ACID; rich indexes (GIST/SP-GIST/BRIN). Includes a Mastering PostGIS distillation. |
| GeoPandas | coding/geopandas/ | Single-node Python, Pandas idiom. Folds raw Shapely. Has explicit no-GDAL fallbacks. |
| Apache Sedona | coding/sedona/ | Distributed spatial joins on Spark. Same skill for PySpark and Scala scaffolding. Includes raster. |
| DuckDB-spatial | coding/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).
| Category | Skill | Description |
|---|---|---|
git-workflow/ | commit | Structured commits with ticket references |
git-workflow/ | branch | Branch naming convention (type/descriptive_string) |
git-workflow/ | create-pr | Pull requests with bidirectional ticket linking |
git-workflow/ | merge | Develop-first merge workflow |
git-workflow/ | develop-guard | Ensure develop branch exists |
session/ | wrap-up | End-of-session commit and documentation cleanup |
session/ | pr-comments | Triage and respond to PR comments |
session/ | coderabbit-response | Triage and respond to CodeRabbit reviews |
planning/ | create-ticket | Create tickets in any platform (GitHub, GitLab, Jira, Linear) |
planning/ | close-ticket | Close with summary comment, linked commits, verification |
planning/ | update-ticket | Add progress, link commits, update fields |
planning/ | pre-work-check | Claim ticket → mark in-progress → branch → start (the pre-flight) |
maintenance/ | consolidate | Find and consolidate redundant documentation |
Analytical Skills
User-invoked. Read-only analysis that produces recommendations.
| Category | Skill | Description |
|---|---|---|
coding/ | code-review | Systematic review: correctness, security, data integrity, performance |
coding/ | qml-component-review | QML component decomposition; properties-in / signals-out discipline |
planning/ | im-feeling-lucky | Prioritize roadmap items by context, age, dependencies, diversity |
thinking/ | think | Design-first gate: structured design before any implementation |
meta/ | check-resolvable | Audit that every skill is reachable from RESOLVER |
Reference Skills
Auto-applied by Claude when relevant. Not behind a router.
| Category | Skill | Description |
|---|---|---|
documentation/ | cascading-documentation | Cascading documentation: inline, files, repo, KMS levels |
documentation/ | notion-knowledge-base | Notion knowledge base authoring at 5th-grade reading level |
infrastructure/ | databricks | Databricks workspace, jobs, DLT, Delta, Unity Catalog, Photon |
infrastructure/ | unity-catalog | Unity Catalog permissioning specifics |
infrastructure/ | ops | Shared-infra guardrails (cyberpower UPS, K8s pod limits, Rundeck concurrency) |
maintenance/ | library-api-evolution | Renaming public functions, changing defaults, dropping columns safely |
Meta Skills
| Category | Skill | Description |
|---|---|---|
meta/ | skillbuilder | Create, 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.jsonfor 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:
- Mastering PostGIS (Witkowski et al., 2017) chapter-by-chapter distillation under
skills/coding/postgis/references/mastering-postgis/ - Geographic Data Science with Python (Rey, Arribas-Bel, Wolf, 2023) distillation under
skills/analysis/spatial/references/geographic-data-science-distilled.md, with topic refs for spatial weights, regionalization, spatial inequality, spatial feature engineering, and point pattern analysis - Universal cross-engine spatial principles at
skills/analysis/spatial/references/principles/-- engine-agnostic patterns (CRS-as-meaning, validate-on-ingest, bbox-pre-filter, subdivide-complex-polygons, indexing-discipline, name-by-srid)
Template Variables
The CLAUDE.md template supports:
| Variable | Example | Source |
|---|---|---|
{{PROJECT_NAME}} | my-project | Directory name or git remote |
{{ORG_NAME}} | siege-analytics | Git remote organization |
{{GIT_ROOT}} | ~/git/siege-analytics | Parent directory |
{{CURRENT_DATE}} | 2026-05-02 | System 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.
| Shelf | Topic |
|---|---|
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
- StrongAI/claude-skills --
claude_initmerges both repos' skills automatically (org skills take priority)
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:
| # | Criterion | Operationalized by |
|---|---|---|
| a | Code-reviewed | /code-review |
| b | Edge cases explored | code-review §1 (concrete checklist) |
| c | Tests written | tests are mandatory; no infrastructure → add it first; PRs without tests must justify |
| d | Non-trivial updates → update the ticket | /update-ticket, /close-ticket |
| e | Work 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.
| Layout | Branch / tag | Skills tree shape | Consumer |
|---|---|---|---|
| nested | release/nested, vX.Y.Z-nested | Skills under category folders (coding/code-review/, git-workflow/commit/, ...) | Claude Code with the resolver hook |
| flat | release/flat, vX.Y.Z-flat | Leaf skills at skills/<slug>/; routers stay at category root | Craft 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-nestedon therelease/nestedbranch -- pull this for Claude Code with the resolver hookv1.0.0-flaton therelease/flatbranch -- 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.