Project structure¶

Current top-level layout:

claude-shared/
├── .claude/                 # local Claude Code settings (not packaged)
├── .claude-plugin/
│   └── plugin.json          # plugin manifest: name, version, author, repo
├── skills/
│   ├── skill-management/
│   │   └── SKILL.md
│   └── spec/
│       ├── SKILL.md
│       └── templates/
│           └── spec.template.md
├── spec/
│   ├── .spec-config.yml
│   ├── README.md            # autogenerated index
│   └── claude/
│       ├── agent-management/
│       │   ├── en.md        # canonical
│       │   └── de.md
│       └── skill-management/
│           ├── en.md
│           └── de.md
├── docs/                    # MkDocs sources (this site)
├── mkdocs.yml
└── README.md

Planned but not yet created:

agents/                      # reusable sub-agent definitions

What goes where¶

The table below maps each kind of content to its location on disk:

Content	Location
Plugin manifest	`.claude-plugin/plugin.json`
Skill sources	`skills/<name>/`
Skill templates/refs	`skills/<name>/templates/`, `references/`, `examples/`
Agent sources	`agents/<name>.md` (single self-contained file; no sibling folder)
Specifications	`spec/<topic>/<slug>/<lang>.md`
Spec config	`spec/.spec-config.yml`
Spec index	`spec/README.md` (autogenerated—don't hand-edit)
User documentation	`docs/<lang>/…`

Languages¶

Three language conventions apply across the repository:

Skill and agent content: English—this keeps Claude's processing cost low. Skills/agents may still instruct Claude to respond to the user in the user's language.
Specifications: canonical EN, translation DE, structurally in sync.
Documentation (docs/): DE and EN via mkdocs-static-i18n.

Plugin namespace¶

The plugin is called nolte-shared (see .claude-plugin/plugin.json). Skills are invocable as /nolte-shared:<skill>. The plugin name stays stable—it's part of every invocation and every document.

Tech stack¶

The repository is a documentation-and-automation project rather than a compiled application: there is no runtime service, only a Claude Code plugin plus the tooling that authors, lints, and publishes it. The canonical inventory of these building blocks—each with its kind, group, role, and source-of-truth file—is the hand-curated portfolio source portfolio/tech-stack.yml (governed by spec/portfolio/tech-stack/); the list below mirrors it and must not drift from it.

Component	Role	Source of truth
Python	Runtime for the validation, catalog-generation, and journal scripts under `scripts/`	`scripts/`
MkDocs (Material + static-i18n)	Documentation generator producing the bilingual site under `docs/`	`mkdocs.yml`
Task	Task orchestrator running the quality-gate, docs, lint, and dogfooding targets	`Taskfile.yml`
Vale	Prose linter using the pinned `nolte/vale-style` vocabularies	`.vale.ini`
pre-commit	Hook framework wiring whitespace, YAML, Markdown, and Vale checks	`.pre-commit-config.yaml`
Renovate	Automated dependency-update bot extending the `nolte/gh-plumbing` preset	`renovate.json5`
GitHub Actions	CI provider running the lint, test, docs, and release workflows	`.github/workflows/`

Pinning intent: every MkDocs plugin is pinned in docs/requirements.txt, the Vale style is pinned to a nolte/vale-style release in .vale.ini, and the reusable CI workflows pin their nolte/gh-plumbing version. Project-local additions on top of the portfolio baseline are listed inline above next to the canonical source.

Sources¶

portfolio/tech-stack.yml: canonical portfolio tech-stack inventory (per spec/portfolio/tech-stack/)
Taskfile.yml, mkdocs.yml, .vale.ini, .pre-commit-config.yaml: the per-component source-of-truth files referenced above