Workspace Layout

Defines the canonical Skillset workspace tree, authored source families, generated-output boundary, and operational storage paths.

A Skillset workspace keeps its root skillset.yaml manifest beside a flat .skillset/ source root. These are the authored inputs. Lock-owned build destinations and their provenance are derived generated output, not competing source truth. Setup may also create authored or user-owned scaffolds, including the root manifest and an optional CI workflow; those files remain user-owned configuration rather than disposable output.

Authored workspace

skillset.yaml
.skillset/
  RULES.md
  subagents/
    <agent-name>.md
  changes/
  hooks/
  plugins/
    <plugin-name>/
      skillset.yaml
      README.md
      subagents/
      commands/
      hooks/
      shared/
        partials/
      skills/
      _claude/
      _codex/
      _cursor/
  rules/
    <topic>.md
  shared/
    assets/
    references/
    scripts/
    templates/
    partials/
  skills/
    <skill-name>/
      SKILL.md
  tests.yaml
  tests/
  _claude/
  _codex/
  _cursor/

Only the families a repository uses need content. Setup may retain empty families with placeholders so their intended ownership remains visible.

The root skillset.yaml owns workspace configuration and root source metadata. Plugin directories derive their identity from <plugin-name> and carry their own skillset.yaml. Skill directories derive their identity from <skill-name> and use SKILL.md as their entry point. Do not reintroduce the retired .skillset/config.yaml, .skillset/skillset.yaml, .skillset/src/, or root skillset/ layouts; current source loading rejects them.

Use the project configuration guide for the root manifest, the frontmatter guide for document metadata, and the generated schemas and examples for exhaustive field shapes.

Source families

Support files beside a SKILL.md, such as references/, scripts/, assets/, and templates/, already belong to that skill. Root shared/ and plugin-local shared/ are for material reused by multiple skills. Shared material is not copied merely because it exists: a skill declares the resources it needs. The resources reference owns declaration, copy, link-rewrite, and executable-mode behavior.

Provider-native islands

Directories named _claude, _codex, and _cursor are explicit target-native islands. At the workspace root, their contents mirror to that provider’s project root. Inside a plugin, supported companion files mirror only into that plugin’s generated bundle. Codex plugin .rules files are unsupported and fail instead of being copied; Codex command-policy files belong only to the workspace-level _codex/rules/ island.

These directories preserve provider-shaped files when there is no adaptive representation. They do not make a provider active and they do not turn provider capabilities into portable support. Consult the support matrix and owning feature page before choosing an island.

Codex command-policy files are one important distinction: .skillset/_codex/rules/**/*.rules can mirror to .codex/rules/**/*.rules, while portable rule prose under .skillset/rules/ renders through discovered AGENTS.md files. See Rules.

Generated destinations and provenance

An enabled target receives files in its native repository layout. Standalone skills normally render below .claude/skills/, .agents/skills/, or .cursor/skills/; plugin-owned skills render once inside plugins/<plugin>/skills/; project rules render to Claude and Cursor rule roots or Codex AGENTS.md files; provider manifests and supported components share the same plugins/<plugin>/ package. Custom package placement remains unsupported until SET-561. A plugin-owned skill appears in a repository skill root only through a separately owned project-use projection.

Nearby skillset.lock files record source paths, destination ownership, projection role, hashes, and render evidence. Current locks distinguish standard, project-use, and provider bundle roles. Each lock entry carries its own provenance hash and a header hash covers the configuration-derived fields, so branches that change different units edit different lock lines and merge as plain text (ADR-0045). Generated paths are reviewable and may be committed, but edit .skillset/ when the intent is portable. Use skillset explain <path> to trace one source or destination and its role, and skillset check --only outputs to detect drift. Exact flags belong to the generated CLI reference.

Skillset renders files. It does not install, trust, activate, symlink, or mutate user-level provider configuration. Build and activation are separate workflows.

skillset move <from> <to> moves one shipped skill between .skillset/skills/<leaf> and .skillset/plugins/<plugin>/skills/<leaf> inside this workspace. It preserves the leaf identity, carries only a same-container _drafts/<leaf> sibling, rewrites current source selectors, and appends identity history without rewriting old change records. External checkouts, another workspace, arbitrary directories, and leaf changes are refused before any write. The command is plan-first; rerun the displayed operation with --yes to apply it atomically.

Operational storage and lifetimes

Skillset keeps authored source, reproducible output, temporary operational evidence, recovery material, and durable operation receipts in separate stores. The logical .skillset/cache/... paths printed by workspace commands resolve to the repository’s XDG cache bucket; they are not physical repo directories.

Use skillset report show <id-or-path> to inspect a completed immutable report. Existing test, eval, CI, adoption, and fixture evidence keeps its producer-specific cache path and reader until an explicit migration; a cache report does not become a global receipt merely because both contain structured results.

Unset, empty, or relative XDG values fall back to the listed home-relative bases. Per-repository cache buckets use workspace.cacheKey when explicitly configured; otherwise Skillset derives a machine-local key from the checkout. Most repositories should keep the automatic key.

Logical .skillset/cache/<suffix> paths map to $XDG_CACHE_HOME/skillset/<repo-key>/<suffix>. An explicit workspace.cacheKey supplies a lowercase <repo-key> of at most 160 characters; otherwise Skillset derives <basename>--local-<sha12> from the checkout. The managed known-workspaces index is machine-local configuration used to resolve local repository identities. It is disposable convenience state, not committed source or portable verification evidence.

Current public commands remain repository-local unless an existing command receives an explicit root; the prospective workspace in the global/XDG draft ADR is not an implemented fallback.