Skip to content

Conventions

Shared conventions that all dotStandards follow. Individual specifications reference this page instead of repeating common rules.

File format

All content files use Markdown (.md extension) with UTF-8 encoding. Configuration and manifest files use YAML (.yml extension) with UTF-8 encoding.

No binary formats, no JSON (except where a tool requires it), no proprietary encodings.

Naming

  • Lowercase slugs with hyphens as separators: my-organization.md, container-setup.md.
  • No spaces, no underscores, no camelCase in file or directory names.
  • Directory names are plain words or short phrases: profile/, techdocs/, pipelines/.

Directory layout

  • Dot-prefixed directories at well-known locations: ~/.agents/, .forge/.
  • Shallow hierarchies. One or two levels of nesting is typical. Deep trees are discouraged — if you need more than three levels, the structure is probably too complex.
  • The directory layout itself carries meaning. A file at profile/user.md is a user profile because of where it is, not because of a config entry that says so.

Reserved names

Dot-prefixed names (.config, .acl, etc.) at the root of a dotStandards directory are reserved for tool-specific configuration and metadata. Standards define which dot-prefixed names they use; all others are available for tool authors.

Frontmatter

Files may include YAML frontmatter, but no standard requires specific frontmatter keys. Tools must not break if frontmatter is absent.

For content quality recommendations (structure, conciseness, self-containment), see the general guidelines.

Extensibility

All dotStandards follow the same extensibility model:

  • The standard defines a minimal required structure (often just one file).
  • Additional files and directories can be added freely.
  • Custom additions should use descriptive names and avoid collisions with reserved names.
  • Tools should ignore files and directories they do not recognize rather than failing.

Versioning

Standards use simple major.minor versioning (e.g., v0.1, v1.0). Breaking changes increment the major version. Additive changes increment the minor version.