@dzhechkov/skills-12factor

12 decision-moment skills distilled from The Twelve-Factor App — one per factor — so AI coders (Claude Code, Codex, …) apply 12-factor decisions at the moments they arise: where config lives, how processes hold state, how services bind ports, how to keep dev/prod in parity, …

Generated by @dzhechkov/skills-book-digitizer — the first public example of a digitized-book skill pack. Derivative of The Twelve-Factor App, CC BY 4.0, attribution in NOTICE.

The 12 skills (one per factor)

| Skill | Factor | Decision it captures | |-------|--------|----------------------| | 12factor-codebase-repo-mapping | I | one codebase per app, many deploys | | 12factor-explicit-dependencies | II | declare + isolate dependencies explicitly | | 12factor-config-in-environment | III | store per-deploy config in the environment, not code | | 12factor-backing-services-as-resources | IV | treat databases/queues/caches as attached, swappable resources | | 12factor-build-release-run-separation | V | strictly separate build, release, run | | 12factor-stateless-processes | VI | stateless, share-nothing; persist to backing services | | 12factor-port-binding | VII | export via port binding, self-contained | | 12factor-concurrency-process-model | VIII | scale out via the process model / process types | | 12factor-disposability-fast-startup | IX | fast startup, graceful + robust shutdown | | 12factor-dev-prod-parity | X | keep dev, staging, prod as similar as possible | | 12factor-logs-as-streams | XI | treat logs as event streams to stdout | | 12factor-admin-processes | XII | run one-off admin tasks in a production-identical environment |

Each skill ships a house-format SKILL.md (Decision · Protocol · Anti-patterns · Related decisions · Источник · Self-check · Examples), page-cited Knowledge Units in references/, and routing evals in evals/. trust_tier 0 — machine-distilled from the source, unreviewed; promote with human review.

Install into an agent

The easy way — install the whole pack in one command:

dz install @dzhechkov/skills-12factor --target claude-code

That's it — all 12 skills land in .claude/skills/. Then just talk to Claude Code in plain language and it activates the right skill automatically (routing-gated — you never type skill ids):

«Используй нужные скиллы из набора 12factor, чтобы решить задачу: <опиши задачу или дай ссылку на сервис>.» (EN: "Use the relevant 12factor skills to solve: <your task>.")

Advanced — just one decision: if you only want a single skill, install it directly:

dz init --target claude-code --select 12factor-config-in-environment

Targets: claude-code · codex · opencode · hermes · openclaude · copilot. The agent activates each skill on its decision moment (validated by a CP3.5 routing gate: 100% activation / 0% sibling-steal across 103 positives + 82 hard-negatives).

Make a portable bundle

dz bundle --select 12factor-config-in-environment,12factor-stateless-processes --out ./12factor-bundle

Self-contained skills/ tree for a generic / LangGraph consumer.

Usage scenarios

Install the pack once (dz install @dzhechkov/skills-12factor --target claude-code), then just describe your task to Claude Code in plain language — the agent auto-activates the right skills. No skill ids to memorize. Here are the situations where this pack pays off, with example prompts you can copy and adapt:

1. Audit an existing service for 12-factor compliance

Situation: you inherited a service and want to know where it drifts from cloud-native best practice before you containerize or move it to k8s.

«Используй скиллы 12factor: прогони этот сервис по двенадцати факторам и укажи, где он их нарушает, с приоритетом по риску.» (EN: "Using the 12factor skills, audit this service against the twelve factors; list violations, highest-risk first.")

What happens: the agent walks the code applying each decision skill's criteria — e.g. 12factor-config-in-environment flags hard-coded DB URLs/secrets (its litmus test: "could the repo go public without leaking credentials?"), 12factor-stateless-processes flags in-process session/cache state, 12factor-logs-as-streams flags a service writing its own log files. You get a prioritized, criteria-backed compliance report, not vibes.

2. Design a new cloud-native service correctly from day one

Situation: greenfield — you want the scaffolding to be 12-factor by construction, not retrofitted.

«Используй скиллы 12factor: спроектируй скелет нового сервиса заказов — как разложить репозиторий, зависимости, конфиг и стадии сборки/релиза/запуска.»

What happens: the agent makes the early structural decisions with the factors' rationale — one codebase→many deploys, an explicit dependency manifest with isolation, config via env, a strict build/release/run split, a port-bound self-contained process — and explains why at each fork.

3. Make one decision, right now, at the moment it arises

Situation: you hit a specific fork mid-task and want the principled answer, cited.

«У меня фича-флаги и ключ к платёжному API — положить в конфиг-файл в репозитории или куда?» (EN: "Feature flags + a payment API key — a config file in the repo, or where?")

What happens: 12factor-config-in-environment activates (routing-gated to fire on exactly this decision), applies the "config vs code" separation + the open-source litmus test, and distinguishes per-deploy config (→ env) from internal app config (→ code) — with the Twelve-Factor citation.

4. Get to container/k8s readiness

Situation: you're Dockerizing/moving to Kubernetes and need the runtime-shape decisions right so the platform can scale, restart, and roll your app safely.

«Используй скиллы 12factor: подготовь этот сервис к запуску в Kubernetes — порты, graceful shutdown, масштабирование, логи.»

What happens: 12factor-port-binding (bind a port, self-contained), 12factor-disposability-fast-startup (fast start + SIGTERM graceful shutdown + crash-safety), 12factor-concurrency-process-model (scale out via process types, map to replicas), 12factor-logs-as-streams (stdout, let the platform collect) — the exact decisions that make a container behave under an orchestrator.

5. Teach the "why" (onboarding / review)

Situation: a teammate asks why the app is built this way, or you want a review that explains the rationale, not just the rule.

«Объясни, почему у нас stateless-процессы и логи в stdout — какие проблемы это решает?»

What happens: the relevant skills surface the factor's reasoning (share-nothing → horizontal scale & crash-safety; logs-as-streams → the platform, not the app, owns routing/retention), grounded in the source with attribution — useful for onboarding docs and PR review comments.

Quality & provenance

• Paraphrased, not copied — a deterministic word-shingling gate (w=8) enforces no uncited verbatim run ≥ 8 words; the pack passes with 0 (cited ≤25-word quotes are exempt).
• Routing-gated — an LLM-judge oracle over the full description catalog confirms each skill activates on its own decision and not a sibling's.
• Attribution (CC BY 4.0) — every skill's «Источник» + NOTICE credit The Twelve-Factor App authors. This derivative is distributed under the same CC BY 4.0.

License

CC BY 4.0 — © the Twelve-Factor App authors for the underlying work; this derivative pack is licensed CC BY 4.0. See LICENSE and NOTICE. You may use, share, and adapt with attribution.