# Component Development > Atmos core component development: adding or changing native component types, component registry providers, commands, stack schema, docs, examples, DAG/affected behavior, auth, hooks, source/provisioning, and tests - Skill: `cloudposse/component-development` (Agent Skill) - Install (CLI): `npx skillmds@latest add cloudposse/component-development` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudposse/component-development/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: cloudposse (https://skillmd.com/u/cloudposse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cloudposse/component-development --- # Component Development Use this skill when adding or changing an Atmos native component type or shared component behavior. ## Start With The Existing Contract Inspect comparable component types before designing: ```bash rg -n "ComponentType|SectionName|components\\..*base_path" pkg/config pkg/schema rg -n "component.Register|ComponentProvider|Execute\\(" pkg/component cmd internal rg -n "process.*ComponentsIndexed|ExecuteGraph|dependencies.components" internal pkg ``` For stack-surface decisions, compare Terraform, Helmfile, Packer, and Ansible. Reuse shared sections when they already exist: - `metadata` - `vars` - `env` - `settings` - `hooks` - `auth` - `dependencies` - `generate` - `source` - `provision` Do not invent nested settings for component-owned inputs. If an instance is `components..`, component-specific inputs belong directly under that instance, e.g. `components.kubernetes.argocd.paths`, not `settings.kubernetes.paths`. ## Required Wiring For a new component type, update all applicable surfaces in one PR: - Constants: `pkg/config/const.go` - CLI/default config structs: `pkg/schema/schema.go` - Defaults: `pkg/config/default.go` - Config path resolution: `pkg/config/config.go`, `pkg/utils/component_path_utils.go` - Component registry provider: `pkg/component//` - Command package: `cmd//` - Root side-effect imports: `cmd/root.go` - Source provisioning base path support: `pkg/provisioner/source/` - Hooks/events if lifecycle hooks are supported: `pkg/hooks/` - Affected detection: `internal/exec/describe_affected_*` - DAG/bulk execution if `--all` or `--affected` is supported - Embedded CLI usage examples: `cmd/markdown/atmos_*_usage.md` - Runtime stack schemas: `pkg/datafetcher/schema/atmos/manifest/1.0.json` and `pkg/datafetcher/schema/stacks/stack-config/1.0.json` - LSP hints if stack authoring changes: `pkg/lsp/server/` - Docs: command docs, stack component docs, `atmos.yaml` config docs - Examples under `examples/` for user-visible component types If a public website schema file exists in the checkout, update it too. Do not assume it exists; verify with `find website/static -path '*schema*'`. ## Command Behavior Commands should be Atmos-native, not thin binary wrappers, when the implementation owns behavior. - Use the component registry provider rather than hard-coded command logic. - Use `flags.NewStandardParser()` for command-specific flags. - Preserve `--identity` and profile handling. - For bulk operations, allow zero positional component args with `--all` or `--affected`. - Reject ambiguous forms such as component arg plus `--all`. - Use dotted hook events such as `before..` and `after..`. - Add embedded usage examples for every public subcommand. If a command name like `kubectl` or `kustomize` is used as a provider, be explicit whether it means CLI execution or compatible behavior. For SDK-backed providers, do not add a `command` override unless a binary is actually executed. ## Auth Thread Auth through stack processing and execution: - Parse global `--identity` into `ConfigAndStacksInfo.Identity`. - Use the same auth setup path as existing component commands when stack YAML functions or integrations need credentials. - Keep component-level `auth:` in the stack schema. - For Kubernetes-like SDK clients, create the client after Auth has prepared environment or kubeconfig integration output. - Prefer plain `ambient` for local examples that should respect the surrounding environment without prompting for provider login. Use concrete provider identities for examples that actually require a cloud or service-specific authentication flow. ## DAG And Affected If the component supports `--all` or `--affected`: - Build nodes from `components.`. - Skip abstract, disabled, and locked components where applicable. - Use `dependencies.components` as the primary dependency source. - Keep legacy `settings.depends_on` only as compatibility. - Process in topological order. - For `--affected`, run affected detection first, filter to the component type, then graph-filter selected nodes. - Include dependencies by default so prerequisites run before selected nodes. - Make `--include-dependents` explicit for downstream components. Affected detection must include both implementation path changes and stack config changes. For new component-specific top-level sections, add affected reasons for those sections. ## Schemas And Docs Schema and docs are part of the feature, not follow-up polish. Update stack schemas with the exact component shape. Validate Atmos-owned fields strictly, but keep domain resources permissive when a complete third-party schema would be brittle. Example: validate Kubernetes manifest entries have `apiVersion` and `kind`, but do not model the entire Kubernetes API. Docs must cover: - `atmos.yaml` configuration - Stack component configuration - Every command and flag - Reusable sections supported by the component - Auth behavior - Hooks and lifecycle events - Dependencies, `--all`, and `--affected` - Examples for file paths, inline manifests/config, render/generate behavior, source/provisioning when supported Use the local docs skill for website docs conventions. Command and component docs must explain the user outcome before implementation details. Do not open intros with mechanical phrasing such as "Use this command to..." or with internal architecture such as providers, SDKs, DAGs, or stack processing unless that detail changes how the user should operate the feature. Lead with what the user can accomplish, when they should reach for the command or configuration page, and the next action they can take. ## Examples Examples should be runnable and reflect the intended user model: - Use local infrastructure like k3s when possible. - Keep command examples working without cloud credentials unless the example is explicitly cloud-auth focused. - If Auth is part of the feature, include a local identity path and a commented real-cloud integration example when useful. - Add separate examples for materially different providers or modes. ## Validation Run focused tests first: ```bash go test ./pkg/component/ ./cmd/ go test ./pkg/config ./pkg/schema ./pkg/hooks ./pkg/provisioner/source go test ./internal/exec ./pkg/lsp/server jq empty pkg/datafetcher/schema/atmos/manifest/1.0.json jq empty pkg/datafetcher/schema/stacks/stack-config/1.0.json ``` For docs: ```bash pnpm --dir website exec prettier --check "docs/**/*.{mdx,json}" ``` For examples: ```bash (cd examples/ && atmos validate stacks) (cd examples/ && atmos render -s ) ``` If a validation failure is pre-existing or requires external services, say that explicitly and include the narrow command that failed.