schema-sidecar 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. schema_sidecar/.claude-plugin/marketplace.json +16 -0
  2. schema_sidecar/.claude-plugin/plugin.json +10 -0
  3. schema_sidecar/README.md +31 -0
  4. schema_sidecar/__init__.py +1 -0
  5. schema_sidecar/__main__.py +5 -0
  6. schema_sidecar/cli.py +407 -0
  7. schema_sidecar/skills/linkml-author/SKILL.md +128 -0
  8. schema_sidecar/skills/linkml-author/references/generators.md +33 -0
  9. schema_sidecar/skills/linkml-author/references/lmodel-profile.md +35 -0
  10. schema_sidecar/skills/linkml-author/references/metamodel.md +329 -0
  11. schema_sidecar/skills/linkml-author/references/publishing.md +72 -0
  12. schema_sidecar/skills/linkml-author/references/schema-design.md +115 -0
  13. schema_sidecar/skills/linkml-author/references/source-mapping.md +43 -0
  14. schema_sidecar/skills/linkml-sidecar/SKILL.md +173 -0
  15. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.codespellrc +5 -0
  16. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.editorconfig +22 -0
  17. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.github/dependabot.yml +16 -0
  18. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.github/workflows/codespell.yml +31 -0
  19. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.github/workflows/test-template.yml +44 -0
  20. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.github/workflows/typos.yml +27 -0
  21. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.gitignore +137 -0
  22. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.pre-commit-config.yaml +27 -0
  23. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.typos.toml +9 -0
  24. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.yamllint.yaml +12 -0
  25. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/.zenodo.json +39 -0
  26. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/CHANGELOG.md +396 -0
  27. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/CITATION.bib +11 -0
  28. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/CONTRIBUTING.md +108 -0
  29. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/LICENSE +21 -0
  30. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/README.md +267 -0
  31. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/copier.yaml +148 -0
  32. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/includes/README.md +7 -0
  33. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/includes/slugify.jinja +4 -0
  34. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/Apache-2.0 +201 -0
  35. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/BSD-3-Clause +28 -0
  36. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/GPL-3.0-only +674 -0
  37. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/LGPL-3.0-only +165 -0
  38. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/MIT +22 -0
  39. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/licenses/MPL-2.0 +373 -0
  40. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/pyproject.toml +14 -0
  41. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.editorconfig +18 -0
  42. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.github/dependabot.yml +13 -0
  43. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.github/workflows/deploy-docs.yaml +62 -0
  44. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.github/workflows/main.yaml +55 -0
  45. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.github/workflows/{% if gh_action_docs_preview %}test_pages_build.yaml{% endif %}.jinja +71 -0
  46. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.github/workflows/{% if gh_action_pypi %}pypi-publish.yaml{% endif %}.jinja +95 -0
  47. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.gitignore +144 -0
  48. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.pre-commit-config.yaml +50 -0
  49. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/.yamllint.yaml +19 -0
  50. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/CODE_OF_CONDUCT.md.jinja +76 -0
  51. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/CONTRIBUTING.md.jinja +121 -0
  52. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/README.md.jinja +34 -0
  53. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/config.public.mk.jinja +29 -0
  54. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/config.yaml +63 -0
  55. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/docs/about.md.jinja +3 -0
  56. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/docs/elements/.gitkeep +0 -0
  57. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/docs/index.md.jinja +5 -0
  58. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/docs/js/extra-loader.js +2 -0
  59. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/docs/templates-linkml/README.md +7 -0
  60. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/examples/README.md.jinja +9 -0
  61. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/justfile +295 -0
  62. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/mkdocs.yml.jinja +78 -0
  63. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/project/README.md.jinja +6 -0
  64. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/project.justfile +5 -0
  65. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/pyproject.toml.jinja +82 -0
  66. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/README.md +4 -0
  67. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/{{project_slug}}/__init__.py.jinja +10 -0
  68. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/{{project_slug}}/_version.py +8 -0
  69. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/{{project_slug}}/datamodel/__init__.py.jinja +9 -0
  70. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/{{project_slug}}/schema/README.md +3 -0
  71. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/src/{{project_slug}}/schema/{% if add_example %}{{ project_slug }}.yaml{% endif %}.jinja +98 -0
  72. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/__init__.py.jinja +1 -0
  73. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/README.md.jinja +14 -0
  74. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/invalid/.gitkeep +0 -0
  75. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/invalid/{% if add_example %}Person-002.yaml{% endif %}.jinja +6 -0
  76. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/problem/invalid/.gitkeep +0 -0
  77. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/problem/valid/.gitkeep +0 -0
  78. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/valid/.gitkeep +0 -0
  79. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/valid/{% if add_example %}Person-001.yaml{% endif %}.jinja +6 -0
  80. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/data/valid/{% if add_example %}PersonCollection-001.yaml{% endif %}.jinja +10 -0
  81. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/tests/{% if add_example %}test_data.py{% endif %}.jinja +27 -0
  82. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/{% if not existing_license_file %}LICENSE{% endif %}.jinja +13 -0
  83. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/template/{{_copier_conf.answers_file}}.jinja +2 -0
  84. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/__init__.py +0 -0
  85. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/conftest.py +49 -0
  86. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/helpers.py +91 -0
  87. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/test_generation.py +202 -0
  88. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/test_integration.py +82 -0
  89. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/test_licenses.py +115 -0
  90. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier/tests/test_options.py +57 -0
  91. schema_sidecar/skills/linkml-sidecar/assets/linkml-project-copier.json +7 -0
  92. schema_sidecar/skills/linkml-sidecar/references/automation.md +38 -0
  93. schema_sidecar/skills/linkml-sidecar/references/layouts.md +70 -0
  94. schema_sidecar/skills/linkml-sidecar/references/portability.md +81 -0
  95. schema_sidecar/skills/linkml-sidecar/references/prerequisites.md +34 -0
  96. schema_sidecar/skills/linkml-sidecar/references/template-assumptions.md +30 -0
  97. schema_sidecar/skills/linkml-sidecar/scripts/linkml-scaffold.py +1393 -0
  98. schema_sidecar/skills/linkml-sidecar/scripts/linkml-scaffold.sh +54 -0
  99. schema_sidecar/skills/linkml-sidecar/templates/answers.yml +20 -0
  100. schema_sidecar/skills/linkml-sidecar/templates/forgejo/linkml-sidecar.yaml +113 -0
  101. schema_sidecar/skills/linkml-sidecar/templates/github/linkml-sidecar.yaml +165 -0
  102. schema_sidecar/skills/linkml-sidecar/templates/linkml/LICENSE.missing +5 -0
  103. schema_sidecar/skills/linkml-sidecar/templates/linkml/README-adopted.md +3 -0
  104. schema_sidecar/skills/linkml-sidecar/templates/linkml/README.md +102 -0
  105. schema_sidecar/skills/linkml-sidecar/templates/linkml/docs/about.md +7 -0
  106. schema_sidecar/skills/linkml-sidecar/templates/linkml/docs/index.md +8 -0
  107. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema/plain/schema.yaml +108 -0
  108. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema/plain/tests/data/invalid/Person-002.yaml +6 -0
  109. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema/plain/tests/data/valid/Person-001.yaml +7 -0
  110. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema/plain/tests/data/valid/PersonCollection-001.yaml +10 -0
  111. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema/plain/tests/test_data.py +26 -0
  112. schema_sidecar/skills/linkml-sidecar/templates/linkml/schema-folder-README.md +3 -0
  113. schema_sidecar/skills/linkml-sidecar/templates/llms-section.md +12 -0
  114. schema_sidecar/skills/linkml-sidecar/templates/llms.txt +3 -0
  115. schema_sidecar/skills/linkml-sidecar/templates/project.justfile.append +20 -0
  116. schema_sidecar/skills/linkml-sidecar/templates/project.justfile.merged +12 -0
  117. schema_sidecar/skills/linkml-sidecar/templates/readme-for-schema.md +12 -0
  118. schema_sidecar/skills/linkml-sidecar/templates/scripts/linkml-preflight.sh +583 -0
  119. schema_sidecar-0.7.0.dist-info/METADATA +54 -0
  120. schema_sidecar-0.7.0.dist-info/RECORD +124 -0
  121. schema_sidecar-0.7.0.dist-info/WHEEL +4 -0
  122. schema_sidecar-0.7.0.dist-info/entry_points.txt +2 -0
  123. schema_sidecar-0.7.0.dist-info/licenses/LICENSE +201 -0
  124. schema_sidecar-0.7.0.dist-info/licenses/carried-template/linkml-project-copier/LICENSE +21 -0
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "schema-sidecar",
3
+ "owner": { "name": "Noel McLoughlin", "url": "https://github.com/noelmcloughlin" },
4
+ "metadata": {
5
+ "description": "Agent skills that give a repository a LinkML data model, at its root or as a sidecar."
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "schema-sidecar",
10
+ "source": "./",
11
+ "description": "Two agent skills that give a repository a LinkML data model: linkml-sidecar installs a linkml-project-copier project, at the root of an empty repository or as a hidden .linkml/ sidecar beside the code of any other, and linkml-author turns its dummy schema into the real model and keeps it generated, documented and tested. A KTL knowledge bundle beside it is left to KTL.",
12
+ "category": "development",
13
+ "keywords": ["linkml", "schema", "data-model", "copier", "linkml-project-copier", "sidecar", "json-schema", "pydantic", "owl", "shacl", "lokf", "ktl", "domain-schema", "agent-skills"]
14
+ }
15
+ ]
16
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "schema-sidecar",
3
+ "displayName": "Schema Sidecar",
4
+ "description": "Two agent skills that give a repository a LinkML data model: linkml-sidecar installs a linkml-project-copier project, at the root of an empty repository or as a hidden .linkml/ sidecar beside the code of any other, and linkml-author turns its dummy schema into the real model and keeps it generated, documented and tested. A KTL knowledge bundle beside it is left to KTL.",
5
+ "author": { "name": "Noel McLoughlin", "url": "https://github.com/noelmcloughlin" },
6
+ "homepage": "https://w3id.org/lmodel/schema-sidecar/",
7
+ "repository": "https://github.com/lmodel/schema-sidecar",
8
+ "license": "Apache-2.0",
9
+ "keywords": ["linkml", "schema", "data-model", "copier", "linkml-project-copier", "sidecar", "json-schema", "pydantic", "owl", "shacl", "lokf", "ktl", "domain-schema", "agent-skills"]
10
+ }
@@ -0,0 +1,31 @@
1
+ # schema-sidecar
2
+
3
+ Two [Agent Skills](https://agentskills.io) that give any repository a [LinkML](https://linkml.io) data model: one schema file from which JSON Schema, Pydantic models, OWL, SHACL, TypeScript and a documentation site are generated.
4
+
5
+ - **linkml-sidecar** lays down a [linkml-project-copier](https://github.com/linkml/linkml-project-copier) project, at the root of an empty repository or as a `.linkml/` sidecar beside the code of any other.
6
+ - **linkml-author** turns its dummy schema into the real model and keeps it generated, documented and tested.
7
+
8
+ The package also carries the template linkml-sidecar lays down, at the version the skill pins, and the scaffold checks that copy against the pin before it uses it.
9
+
10
+ ## Install the skills
11
+
12
+ ```bash
13
+ uvx schema-sidecar skills install --scope user
14
+ ```
15
+
16
+ With no `--agent`, the skills go where GitHub Copilot reads them. Name another agent, or a folder:
17
+
18
+ ```bash
19
+ uvx schema-sidecar skills install --agent claude-code --scope user
20
+ uvx schema-sidecar skills install --agent codex --scope project
21
+ uvx schema-sidecar skills install --dest path/to/skills
22
+ ```
23
+
24
+ `schema-sidecar skills list` names the skills, `schema-sidecar skills path` prints their folder for `gh skill install --from-local` or `npx skills add`, and `schema-sidecar skills status` says whether the copies an agent reads are this release's.
25
+
26
+ Then ask your agent to add a LinkML schema to the repository.
27
+
28
+ ## More
29
+
30
+ - Documentation: <https://w3id.org/lmodel/schema-sidecar/>
31
+ - Source and issues: <https://github.com/lmodel/schema-sidecar>
@@ -0,0 +1 @@
1
+ """schema-sidecar: the two LinkML agent skills, linkml-sidecar and linkml-author, the template linkml-sidecar lays down, and a command that installs them."""
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from schema_sidecar.cli import main
4
+
5
+ sys.exit(main())
schema_sidecar/cli.py ADDED
@@ -0,0 +1,407 @@
1
+ """The `schema-sidecar` command: list, locate, install and check the two
2
+ LinkML agent skills this package carries.
3
+
4
+ The package holds linkml-sidecar and linkml-author under
5
+ `schema_sidecar/skills/` and the Claude Code plugin manifest under
6
+ `schema_sidecar/.claude-plugin/`, each byte for byte as the release tag
7
+ holds them. Inside linkml-sidecar it also holds the copier template the
8
+ skill lays down, linkml-project-copier at the pin, under `assets/`, with a
9
+ record of the tag, commit and git tree it came from. The scaffold uses that
10
+ copy and checks it against the record, so laying down a schema project needs
11
+ no git host.
12
+
13
+ `schema-sidecar skills install` copies the skill folders into the folder an
14
+ agent reads, and calls no other tool, so it works the same on every
15
+ operating system and forge, and with no network once the package is
16
+ installed. `gh skill install --from-local` and `npx skills add` take the
17
+ folder `schema-sidecar skills path` prints, where either is at hand.
18
+ `schema-sidecar skills status` says, for each folder an agent reads, whether
19
+ the skills there are this package's.
20
+
21
+ The command uses the standard library alone and runs on Python 3.9 or
22
+ later, the python3 that RHEL 9 includes. Its verbs and options are those of
23
+ the `ktl` command, so a person who uses both meets one shape.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import argparse
29
+ import os
30
+ import shutil
31
+ import stat
32
+ import sys
33
+ import tempfile
34
+ from pathlib import Path
35
+
36
+ PROG = "schema-sidecar"
37
+
38
+ # Where each agent reads skills, at project scope (relative to the
39
+ # repository's top folder) and at user scope (relative to the home folder),
40
+ # as `gh skill install` places them. An agent not listed here takes --dest.
41
+ # No one folder serves them all: Claude Code reads only its own, and Copilot
42
+ # and Codex differ at user scope. So, as with `gh skill install`, GitHub
43
+ # Copilot is the agent when none is named.
44
+ AGENTS = {
45
+ "claude-code": (".claude/skills", ".claude/skills"),
46
+ "codex": (".agents/skills", ".agents/skills"),
47
+ "github-copilot": (".agents/skills", ".copilot/skills"),
48
+ }
49
+ DEFAULT_AGENT = "github-copilot"
50
+
51
+ # A project folder Copilot-style agents also read, which no installer here
52
+ # writes. `status` checks it too.
53
+ OTHER_PROJECT_FOLDERS = {".github/skills": "github-copilot"}
54
+
55
+ # The template the package carries inside linkml-sidecar, and its record.
56
+ # A copy installed from GitHub has neither, and its scaffold fetches the
57
+ # template instead, so `status` reports their absence apart from a change.
58
+ CARRIED = ("assets/linkml-project-copier/", "assets/linkml-project-copier.json")
59
+
60
+ # Files a copy never needs: bytecode a Python run may have left beside a
61
+ # script.
62
+ IGNORED = shutil.ignore_patterns("__pycache__", "*.pyc")
63
+
64
+
65
+ def package_root() -> Path:
66
+ """Return the folder that holds `skills/` and `.claude-plugin/`.
67
+
68
+ In an installed package that is the `schema_sidecar` package folder. In
69
+ a checkout of the repository, where the build has not copied the skills
70
+ in, it is the repository root, two folders above `src/schema_sidecar/`.
71
+ """
72
+ here = Path(__file__).resolve().parent
73
+ if (here / "skills").is_dir():
74
+ return here
75
+ checkout = here.parent.parent
76
+ if (checkout / "skills" / "linkml-sidecar" / "SKILL.md").is_file():
77
+ return checkout
78
+ raise SystemExit(f"{PROG}: no skills folder in {here} or in a checkout above it; reinstall the package")
79
+
80
+
81
+ def skills_dir() -> Path:
82
+ return package_root() / "skills"
83
+
84
+
85
+ def skill_names() -> list[str]:
86
+ return sorted(p.parent.name for p in skills_dir().glob("*/SKILL.md"))
87
+
88
+
89
+ def version() -> str:
90
+ try:
91
+ from importlib.metadata import PackageNotFoundError, version as dist_version
92
+ except ImportError: # pragma: no cover - every supported Python has it
93
+ return "unknown"
94
+ try:
95
+ return dist_version(PROG)
96
+ except PackageNotFoundError:
97
+ return "0.0.0 (a checkout, not an installed package)"
98
+
99
+
100
+ def scalar(text: str) -> str:
101
+ """One YAML scalar written on one line: plain, single-quoted or double-quoted."""
102
+ text = text.strip()
103
+ if len(text) >= 2 and text[0] == text[-1] == "'":
104
+ return text[1:-1].replace("''", "'")
105
+ if len(text) >= 2 and text[0] == text[-1] == '"':
106
+ return text[1:-1].replace('\\"', '"').replace("\\\\", "\\")
107
+ return text
108
+
109
+
110
+ def read_skill_md(path: Path) -> tuple[dict[str, str], dict[str, str], str]:
111
+ """Split a SKILL.md into its frontmatter values, its metadata block and its body.
112
+
113
+ The skills write each value on one line, plain or quoted, so a line
114
+ reader serves and the package needs no YAML parser. `gh skill install`
115
+ rewrites the file as it installs it: the keys come out sorted, a quoted
116
+ value can come out plain, a metadata block names the source, and the
117
+ blank line after the frontmatter goes. Reading each value, and the body
118
+ without its leading blank lines, undoes all four, so two copies of one
119
+ release read the same however each was installed.
120
+ """
121
+ lines = path.read_text(encoding="utf-8").splitlines()
122
+ values: dict[str, str] = {}
123
+ metadata: dict[str, str] = {}
124
+ if not lines or lines[0].strip() != "---":
125
+ return values, metadata, "\n".join(lines).lstrip("\n")
126
+ key = ""
127
+ for number, line in enumerate(lines[1:], start=1):
128
+ if line.strip() == "---":
129
+ return values, metadata, "\n".join(lines[number + 1 :]).lstrip("\n")
130
+ if line[:1] in (" ", "\t"):
131
+ if key == "metadata" and ":" in line:
132
+ name, value = line.split(":", 1)
133
+ metadata[name.strip()] = scalar(value)
134
+ continue
135
+ if ":" in line:
136
+ key, value = line.split(":", 1)
137
+ key = key.strip()
138
+ if key != "metadata":
139
+ values[key] = scalar(value)
140
+ return values, metadata, ""
141
+
142
+
143
+ def first_sentence(text: str) -> str:
144
+ end = text.find(". ")
145
+ return text if end < 0 else text[: end + 1]
146
+
147
+
148
+ def project_root(start: Path) -> Path:
149
+ """Return the top folder of the repository that holds start: the nearest
150
+ folder at or above it with a `.git` entry, which is a folder in a clone
151
+ and a file in a worktree or a submodule. With none, start itself."""
152
+ for folder in (start, *start.parents):
153
+ if (folder / ".git").exists():
154
+ return folder
155
+ return start
156
+
157
+
158
+ def target_folder(agent: str, scope: str) -> Path:
159
+ project, user = AGENTS[agent]
160
+ return (Path.home() / user) if scope == "user" else (project_root(Path.cwd()) / project)
161
+
162
+
163
+ def install(names: list[str], dest: Path) -> None:
164
+ """Copy each named skill folder into dest, replacing a folder of the
165
+ same name.
166
+
167
+ Every skill is copied into one hidden staging folder in dest first, and
168
+ the old folders are swapped for the new ones only once all are copied.
169
+ So a copy that fails, for want of space, say, leaves the earlier release
170
+ whole rather than half replaced. The staging folder holds each skill a
171
+ level down, where no agent looks for one.
172
+ """
173
+ dest.mkdir(parents=True, exist_ok=True)
174
+ source = skills_dir()
175
+ staging = Path(tempfile.mkdtemp(prefix=".schema-sidecar-", dir=dest))
176
+ try:
177
+ for name in names:
178
+ shutil.copytree(source / name, staging / name, ignore=IGNORED)
179
+ for name in names:
180
+ target = dest / name
181
+ if target.is_symlink() or target.is_file():
182
+ target.unlink()
183
+ elif target.exists():
184
+ shutil.rmtree(target)
185
+ (staging / name).rename(target)
186
+ finally:
187
+ shutil.rmtree(staging, ignore_errors=True)
188
+
189
+
190
+ def files_of(folder: Path) -> dict[str, Path]:
191
+ """Every file in a skill folder by its path inside it, bytecode aside."""
192
+ return {
193
+ p.relative_to(folder).as_posix(): p
194
+ for p in sorted(folder.rglob("*"))
195
+ if p.is_file() and "__pycache__" not in p.parts and p.suffix != ".pyc"
196
+ }
197
+
198
+
199
+ def executable(path: Path) -> bool:
200
+ return bool(path.stat().st_mode & stat.S_IXUSR)
201
+
202
+
203
+ def same_skill_md(a: Path, b: Path) -> bool:
204
+ """Whether two SKILL.md files read the same, gh's metadata block aside."""
205
+ values_a, _, body_a = read_skill_md(a)
206
+ values_b, _, body_b = read_skill_md(b)
207
+ return values_a == values_b and body_a == body_b
208
+
209
+
210
+ def carried(rel: str) -> bool:
211
+ return rel.startswith(CARRIED[0]) or rel == CARRIED[1]
212
+
213
+
214
+ def compare(installed: Path, packaged: Path) -> tuple[list[str], list[str], bool]:
215
+ """Compare an installed skill with this package's copy of it.
216
+
217
+ Return the files whose content differs, or that only one copy holds;
218
+ the files this package marks executable that the installed copy does
219
+ not; and whether the installed copy lacks the carried template that this
220
+ package's holds, as a copy installed from GitHub does. A SKILL.md counts
221
+ as the same when it reads the same through read_skill_md. The skills run
222
+ their scripts through bash, so a lost executable bit is reported apart
223
+ from a change of content.
224
+ """
225
+ mine, theirs = files_of(packaged), files_of(installed)
226
+ no_template = any(carried(rel) for rel in mine) and not any(carried(rel) for rel in theirs)
227
+ if no_template:
228
+ mine = {rel: path for rel, path in mine.items() if not carried(rel)}
229
+ changed = sorted(set(mine) ^ set(theirs))
230
+ not_executable = []
231
+ for rel in sorted(set(mine) & set(theirs)):
232
+ a, b = mine[rel], theirs[rel]
233
+ if a.read_bytes() != b.read_bytes() and not (rel == "SKILL.md" and same_skill_md(a, b)):
234
+ changed.append(rel)
235
+ if os.name != "nt" and executable(a) and not executable(b):
236
+ not_executable.append(rel)
237
+ return sorted(changed), not_executable, no_template
238
+
239
+
240
+ def where(folder: Path) -> str:
241
+ try:
242
+ return "~/" + folder.relative_to(Path.home()).as_posix()
243
+ except ValueError:
244
+ return str(folder)
245
+
246
+
247
+ def folders_to_check(dest: Path | None) -> dict[Path, list[str]]:
248
+ """Each folder an agent reads skills from, with who reads it: the
249
+ project's folders first, then the user's."""
250
+ if dest is not None:
251
+ return {dest: []}
252
+ root = project_root(Path.cwd())
253
+ readers: dict[Path, list[str]] = {}
254
+ for agent, (project, _) in sorted(AGENTS.items()):
255
+ readers.setdefault(root / project, []).append(f"{agent}, project")
256
+ for folder, agent in OTHER_PROJECT_FOLDERS.items():
257
+ readers.setdefault(root / folder, []).append(f"{agent}, project")
258
+ for agent, (_, user) in sorted(AGENTS.items()):
259
+ readers.setdefault(Path.home() / user, []).append(f"{agent}, user")
260
+ return readers
261
+
262
+
263
+ def state(folder: Path, name: str) -> tuple[str, bool]:
264
+ """One installed skill's line in `status`, and whether it matches this package."""
265
+ skill = folder / name
266
+ changed, not_executable, no_template = compare(skill, skills_dir() / name)
267
+ ref = read_skill_md(skill / "SKILL.md")[1].get("github-ref", "")
268
+ source = f"; installed by gh skill from {ref.rsplit('/', 1)[-1]}" if ref else ""
269
+ if changed:
270
+ shown = ", ".join(changed[:3]) + (", ..." if len(changed) > 3 else "")
271
+ count = f"{len(changed)} file{'s' if len(changed) != 1 else ''}"
272
+ return f"differs from this package in {count} ({shown}){source}", False
273
+ notes = []
274
+ if not_executable:
275
+ notes.append(f"{len(not_executable)} script{'s' if len(not_executable) != 1 else ''} lost the executable bit")
276
+ if no_template:
277
+ notes.append("it carries no template, so its scaffold fetches one from GitHub")
278
+ return "same as this package" + (f", though {' and '.join(notes)}" if notes else "") + source, True
279
+
280
+
281
+ def cmd_list(args: argparse.Namespace) -> int:
282
+ for name in skill_names():
283
+ description = read_skill_md(skills_dir() / name / "SKILL.md")[0].get("description", "")
284
+ print(f"{name}\t{first_sentence(description)}")
285
+ return 0
286
+
287
+
288
+ def cmd_path(args: argparse.Namespace) -> int:
289
+ print(package_root() if args.marketplace else skills_dir())
290
+ return 0
291
+
292
+
293
+ def cmd_install(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
294
+ if args.dest is not None and (args.agent or args.scope):
295
+ parser.error("give --dest, or --scope with an optional --agent, not both")
296
+ if args.dest is None and not args.scope:
297
+ parser.error("name the scope (--scope user|project), or a folder with --dest")
298
+ available = skill_names()
299
+ names = sorted(set(args.skill)) if args.skill else available
300
+ unknown = [n for n in names if n not in available]
301
+ if unknown:
302
+ parser.error(f"no skill named {', '.join(unknown)}; this package carries {', '.join(available)}")
303
+ dest = args.dest if args.dest is not None else target_folder(args.agent or DEFAULT_AGENT, args.scope)
304
+ install(names, dest)
305
+ print(f"Installed {len(names)} skill{'s' if len(names) != 1 else ''} from {PROG} {version()} into {dest}: {', '.join(names)}")
306
+ return 0
307
+
308
+
309
+ def cmd_status(args: argparse.Namespace) -> int:
310
+ packaged = skill_names()
311
+ print(f"{PROG} {version()} carries {', '.join(packaged)}.")
312
+ in_step, empty = True, []
313
+ for folder, readers in folders_to_check(args.dest).items():
314
+ present = [name for name in packaged if (folder / name / "SKILL.md").is_file()]
315
+ if not present:
316
+ empty.append(where(folder))
317
+ continue
318
+ print(where(folder) + (f" (read by {'; '.join(readers)})" if readers else ""))
319
+ for name in present:
320
+ line, same = state(folder, name)
321
+ in_step = in_step and same
322
+ print(f" {name:<15} {line}")
323
+ absent = [name for name in packaged if name not in present]
324
+ if absent:
325
+ print(f" {'not here':<15} {', '.join(absent)}")
326
+ if empty:
327
+ print(f"Neither skill is in {', '.join(empty)}.")
328
+ return 0 if in_step else 1
329
+
330
+
331
+ def build_parser() -> argparse.ArgumentParser:
332
+ parser = argparse.ArgumentParser(
333
+ prog=PROG,
334
+ description="List, locate, install and check the two LinkML agent skills this package carries, "
335
+ "linkml-sidecar and linkml-author, with the template linkml-sidecar lays down.",
336
+ )
337
+ parser.add_argument("--version", action="version", version=f"{PROG} {version()}")
338
+ groups = parser.add_subparsers(dest="group", metavar="{skills}")
339
+ skills = groups.add_parser("skills", help="the two skills: list (the default), path, install, status")
340
+ actions = skills.add_subparsers(dest="action", metavar="{list,path,install,status}")
341
+
342
+ actions.add_parser("list", help="name each skill, with the first sentence of its description")
343
+
344
+ path = actions.add_parser("path", help="print the folder that holds the skills")
345
+ path.add_argument(
346
+ "--marketplace",
347
+ action="store_true",
348
+ help="print the folder that holds .claude-plugin/ instead, for `claude plugin marketplace add`",
349
+ )
350
+
351
+ table = "\n".join(
352
+ f" {agent:<15} project: {project}/ user: ~/{user}/" for agent, (project, user) in sorted(AGENTS.items())
353
+ )
354
+ install_parser = actions.add_parser(
355
+ "install",
356
+ help="copy the skills into the folder an agent reads",
357
+ formatter_class=argparse.RawDescriptionHelpFormatter,
358
+ description="Copy the skills into the folder an agent reads, replacing any earlier copy of each.",
359
+ epilog=f"Where each agent reads skills (project scope is relative to the repository's top folder):\n{table}\n\n"
360
+ f"With no --agent, the agent is {DEFAULT_AGENT}. Give --dest for any other agent or folder.",
361
+ )
362
+ install_parser.add_argument(
363
+ "--agent", choices=sorted(AGENTS), help=f"the agent whose folder to use (default: {DEFAULT_AGENT})"
364
+ )
365
+ install_parser.add_argument("--scope", choices=["user", "project"], help="the user's folder, or this project's")
366
+ install_parser.add_argument("--dest", type=Path, help="install into this folder instead")
367
+ install_parser.add_argument(
368
+ "--skill",
369
+ action="append",
370
+ metavar="NAME",
371
+ help="install only this skill; repeat for more (default: both)",
372
+ )
373
+
374
+ status = actions.add_parser(
375
+ "status",
376
+ help="say whether the skills in each folder an agent reads are this package's",
377
+ description="For each folder an agent reads skills from, at project and user scope, say whether each of the "
378
+ "two skills there is the same as this package's copy. A copy gh skill installed counts as the same when only "
379
+ "gh's own rewrite of its SKILL.md differs, and a copy installed from GitHub when only the carried template is "
380
+ "missing. Exits 1 when an installed copy differs, so a script can act on it.",
381
+ )
382
+ status.add_argument("--dest", type=Path, help="check this folder only")
383
+ return parser
384
+
385
+
386
+ def main(argv: list[str] | None = None) -> int:
387
+ parser = build_parser()
388
+ args = parser.parse_args(argv)
389
+ if args.group != "skills":
390
+ parser.print_help()
391
+ return 2
392
+ try:
393
+ if args.action in (None, "list"):
394
+ return cmd_list(args)
395
+ if args.action == "path":
396
+ return cmd_path(args)
397
+ if args.action == "status":
398
+ return cmd_status(args)
399
+ return cmd_install(args, parser)
400
+ except OSError as error:
401
+ reason = error.strerror or str(error)
402
+ print(f"{PROG}: {reason}: {error.filename}" if error.filename else f"{PROG}: {reason}", file=sys.stderr)
403
+ return 1
404
+
405
+
406
+ if __name__ == "__main__": # pragma: no cover
407
+ sys.exit(main())
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: linkml-author
3
+ description: 'Author and evolve the LinkML schema of any repository that holds one: a linkml-project-copier or linkml-project-cookiecutter project wherever it sits, the `.linkml/` sidecar linkml-sidecar installs, or a schema file on its own. Use when: someone asks to add, change or deprecate a class, slot, enum or type; to model a concept, map a specification, standard or document to a schema, or replace the dummy schema with the real model; to refactor or split a schema; to check schema conventions; or to run lint, gen-project, gen-doc or test. Not for installing or repairing the sidecar; that is linkml-sidecar. Not for the files of a KTL bundle''s `.lokf/`, which ktl-librarian keeps, unless a person names one. Keywords: LinkML, schema authoring, data model, classes, slots, enums, mappings, linkml-lint, gen-project, JSON Schema, Pydantic, OWL, domain schema, KTL.'
4
+ license: Apache-2.0
5
+ compatibility: 'Requires bash; every LinkML tool runs through the host''s own environment (`just`, `make`, `uv run` or `poetry run` in the schema project), or through a pinned `uvx --from linkml` when the host has none, never a globally installed one. Works with or without a `.lokf/` KTL bundle, and never writes in one unasked.'
6
+ ---
7
+
8
+ # linkml-author
9
+
10
+ Turn a project's LinkML schema into the model its code, data and documents describe, and keep it linted, generated, documented and tested after every change. The schema is one YAML file (or a few modules) and everything else is generated from it, so this skill edits the schema and runs the recipes; it never edits a generated file.
11
+
12
+ > Sources: linkml.io is the canonical site for the language ([schemas](https://linkml.io/linkml/schemas/), [generators](https://linkml.io/linkml/generators/)). [references/metamodel.md](references/metamodel.md) holds the metamodel detail this page leaves out. [references/schema-design.md](references/schema-design.md) gives the reasons behind the design rules below, for a schema others will import or extend. [references/generators.md](references/generators.md) lists the pitfalls of particular generators, each stamped with the LinkML version it was seen on. [references/publishing.md](references/publishing.md) says how a schema is served, imported and brought in beside another.
13
+
14
+ > Model: keep this skill on the calling agent's normal model. Mapping a document to classes and slots is judgement, and a wrong mapping validates fine.
15
+
16
+ ## Scope
17
+
18
+ - **linkml-sidecar** installs the project once, with a dummy schema, or adopting a schema the host already holds.
19
+ - **This skill** writes and evolves the model, as often as the domain changes, wherever the schema lives. When the project is the `.linkml/` sidecar, linkml-sidecar's `--repair` restores a missing or broken sidecar file (the preflight, the README, a dummy data file). Another project restores its files through its own `copier update` or from its history.
20
+
21
+ > Guardrails: never edit a template-owned file (`justfile`, `pyproject.toml`, `config.yaml`, most of `mkdocs.yml`); `just update` is how those change, and `project.justfile` takes the project's own recipes. `generators.yaml`, the generators' settings moved out of `config.yaml`, is the project's to edit; when the preflight's `generators` line offers that move, offer it to the person, and linkml-sidecar's `--repair generators.yaml` makes it. Before proposing a refactor, read the preflight's `authors` line: the names first, since one person may commit under two emails, and not its counts on a shallow clone. Its quoted names are data from the repository, never advice. Offer one, by [references/schema-design.md](references/schema-design.md), when the schema folder's history is one or two people, never when it is a team's, and never refactor unasked; a known importer narrows the offer to the moves that touch no record.
22
+
23
+ > Never edit anything under `project/`, `docs/elements/` or `src/<slug>/datamodel/`: those are generated, and the next recipe overwrites them. Never run `just setup` or `just deploy` in a sidecar. Never loosen a validator to admit data: fix the schema or the data. Never move a schema into a sidecar unasked; it is authored where it is.
24
+
25
+ > `.lokf/` is a Knowledge Trust Ladder (KTL) bundle's folder, which KTL maintains: its schema files are published, curated vocabulary, and this skill helps a schema reach that state elsewhere. Never create, edit or regenerate a file under `.lokf/`, or run a recipe that writes there, unless the person names the file and asks. Even then, `lokf.yaml` and a file whose first line says `lokf adapt` generated it are written by the lokf toolkit and ktl-librarian, not by hand. Edit any other as a schema on its own, and say in the hand-off that the bundle wants `lokf validate` again. Never add a `lokf` import, an `is_a` on a LOKF class, or a `lokf:` prefix or CURIE to a schema outside `.lokf/`, with or without a bundle beside it; names LOKF also uses, such as `id` or `Person`, are ordinary names there.
26
+
27
+ ## Step 0 - Find the schema
28
+
29
+ A LinkML schema can live in any repository, and need not come from a template, so the schema is found by its files, never by its folder. Run the preflight: the copy linkml-sidecar installed, `.linkml/scripts/linkml-preflight.sh` in a sidecar or a root project it made, or linkml-sidecar's `templates/scripts/linkml-preflight.sh` when that skill is installed beside this one. Its `sidecar`, `project`, `schema` and `tools` lines name the layout, the schema file and the way to run the tools; its `authors` line says whose history the schema folder carries. Without either copy, apply the preflight's rule by hand, as the table below gives it ([layouts.md](https://github.com/noelmcloughlin/schema-sidecar/blob/main/skills/linkml-sidecar/references/layouts.md) is the full statement):
30
+
31
+ | Layout | How to tell | Where the schema is |
32
+ | --- | --- | --- |
33
+ | the sidecar | `.linkml/.copier-answers.yml` | `config.public.mk` in `.linkml/` names it; an adopted schema sits where `LINKML_SCHEMA_SOURCE_DIR` points, outside `.linkml/` |
34
+ | a schema project elsewhere: the root, `linkml/`, any directory one level down, or the one you were started in | a `.copier-answers.yml` whose `_src_path` names `linkml-project-copier`, or a `config.public.mk` (the older cookiecutter renders it too; upstream may retire it, and then the answers' `project_slug` names the schema) | `<dir>/<slug>.yaml` from `config.public.mk`, else `src/<slug>/schema/<slug>.yaml` |
35
+ | a schema file on its own | a `*.yaml` that imports `linkml:types` or names the `linkml:` prefix and has a top-level `classes:`, `slots:`, `enums:`, `types:` or `imports:` key, outside the folders the preflight skips (`docs/`, `tests/`, `project/`, `tmp/`, `.lokf/` and the rest of its `prune` pattern) | where it is |
36
+ | `.linkml/` holding only configuration files | no answers file and no project files in it | not a layout: look on. A root project's `generators.yaml` there is the project's to edit |
37
+
38
+ A `warn lokf` line means an older linkml-sidecar tied the schema to a KTL bundle: before any edit, show the person linkml-sidecar's [layouts.md](../linkml-sidecar/references/layouts.md#an-older-sidecar-beside-a-ktl-bundle), whose move they approve. One schema: work on it. Several, in a project that names none or in a repository with no project: ask the person which one when the session is attended, and list them and stop when it is not. Read the project's `README.md` before editing: in a sidecar it says which files are the template's, which are the host's, and which recipes never to run.
39
+
40
+ **The tools.** Run everything through the host's own environment, in the first form that applies:
41
+
42
+ 1. the project's `justfile`, as `just --justfile <project>/justfile <recipe>`. `just` changes into the project directory itself, and `uvx --from rust-just just` stands in where `just` is not installed;
43
+ 2. its `Makefile`, as `make -C <project> <target>`, with the same names;
44
+ 3. `uv run` or `poetry run`, when the host's `pyproject.toml` names `linkml`;
45
+ 4. else `uvx --from linkml linkml-lint` and `uvx --from linkml gen-project`, naming the version uvx resolved in the hand-off.
46
+
47
+ Never run a `linkml-lint` or `gen-project` found on the path: the versions the host tested with are the ones that count.
48
+
49
+ ## The gate
50
+
51
+ After every schema edit, in this order:
52
+
53
+ ```bash
54
+ just --justfile <project>/justfile lint # linkml-lint, the recommended rules: warnings fail it
55
+ just --justfile <project>/justfile gen-project # every generator in generators.yaml or config.yaml, plus Python, Pydantic, Java, TypeScript, OWL
56
+ just --justfile <project>/justfile test # generate into tmp/, pytest, then the example runner (it does not lint)
57
+ ```
58
+
59
+ `just test` runs no lint, so `lint` comes first. A generator that fails on a schema `lint` accepted is a schema error too; the message names the element. `just gen-doc` then `just testdoc` shows the docs site locally, and `just site` regenerates everything at once. When a project installs its tools for the first time, `just install` comes before the gate.
60
+
61
+ A schema on its own has no recipes: the gate is `linkml-lint <schema>`, then `gen-project -d <a temporary folder> <schema>`, then `linkml-validate -s <schema> -C <Class> <file>` over whatever example data the host keeps, each through the environment Step 0 named. Say in the hand-off that the host has no test harness, and that linkml-sidecar `--adopt <schema>` would give it one.
62
+
63
+ Example data sits beside the schema's tests: `tests/data/valid/<ClassName>-<anything>.yaml` must validate against `ClassName`, and `tests/data/invalid/<ClassName>-<anything>.yaml` must fail; the class is read from the file name. Every class that carries data in the host gets at least one valid example, and every constraint worth having gets one counter-example. An adopted schema's sidecar starts with none; add them first.
64
+
65
+ ## Replacing the dummy
66
+
67
+ A fresh sidecar holds the `Person` example; an adopted or found schema is already the model, so this section is skipped and the next applies. Read the host first, then write the model in one pass and run the gate:
68
+
69
+ 1. **Collect the sources.** Gather the code's types and records (`src/`, `models/`, migrations, OpenAPI or GraphQL documents, JSON samples, database DDL) and the documents that define the domain (a specification, a standard, a glossary). Look for a vocabulary the domain already publishes as LinkML or OWL, and import it rather than describe it again.
70
+ 2. **Map, do not transcribe.** [references/source-mapping.md](references/source-mapping.md) is the table: a persistent noun becomes a class, a controlled list an enum, a property a slot, a relationship a slot with an object range and an inverse, a containment root a `tree_root` class. Paraphrase descriptions; never paste a standard's text into the schema.
71
+ 3. **Write the schema** in the header's namespace (`id`, `default_prefix` and the prefix's IRI stay as the sidecar set them), with every element described, every enum value given a `meaning` when a public term exists, and identifiers set where instances have them. Keep the dummy's data files only while its classes remain; replace them with the real model's examples.
72
+ 4. **Run the gate**, then update `docs/index.md` and `docs/about.md` (host-owned) so the site says what the model is.
73
+ 5. **Hand back** what was guessed: a class whose source was ambiguous, a slot whose range was inferred, a mapping left out for want of a sure match.
74
+
75
+ ## Rules this skill follows
76
+
77
+ These settle the questions an author meets most, each stated once:
78
+
79
+ | Question | Rule |
80
+ | --- | --- |
81
+ | The schema header's `description` | `description: >-` on its own line, with the text indented beneath it; `\|-` on one line is invalid YAML |
82
+ | Element descriptions | one or two plain sentences saying what the element is, fit for a form field's hint or an API field's help text. The JSON Schema, Pydantic and OpenAPI generators copy the description and nothing else. A caveat for users goes in `comments`, a decision or an open question in `notes`, and a clause reference in an annotation |
83
+ | `name` of the schema | the slug, snake_case, the same as the file, the package and `LINKML_SCHEMA_NAME`; `title` carries the human name |
84
+ | Element names | classes and enums `PascalCase`, slots and types `snake_case`, enum values `snake_case`; `linkml-lint`'s `standard_naming` rule enforces this, and a project that wants `UPPER_CASE` values says so in a `.linkmllint.yaml`. In a schema meant to be imported, class names carry a prefix of the schema's own (`AcmeOrder`), a mixin ends in `Mixin`, and an enum is singular with no `Enum` suffix |
85
+ | Permissible values | one style throughout; a value that must carry punctuation, start with a digit or differ from another only by case gets a `title` free of them |
86
+ | Slots or attributes | every field starts as an `attributes:` entry of its class. It becomes a top-level `slots:` entry only when a second class needs the same field with the same meaning, or when it carries a `slot_uri` identity. Fields that unrelated classes share go in a mixin. Never use both forms for one name. The more fundamental the name (`id`, `name`, `type`, `description`), the likelier it clashes on import, so such a field stays an attribute or sits in one mixin, and a base slot the schema means to share carries a `slot_uri` |
87
+ | Modules | a core that imports only `linkml:types`; topic modules that import the core and lint alone; an umbrella that holds only the tree root and is the file the project names; no import cycle |
88
+ | `slot_usage` | refines a slot for one class (range, cardinality, description); it never changes the slot's identity |
89
+ | References between classes | `identifier: true` on the target's key and `range: <Class>` on the referring field, never a string key described in prose; where the objects live, `inlined: true` with `inlined_as_list: true` |
90
+ | Variants of one thing | a hierarchy whose base carries a `designates_type: true` field, never one class with a kind enum and fields that apply "only when"; a holder takes one multivalued field of the base class, not a field per kind |
91
+ | Enum inheritance | none: `is_a` and `inherits` are unsettled upstream and the generators do not apply them; repeat the values, or share their `meaning` terms |
92
+ | Versions | `version:` carries the full version; element IRIs carry only the part that breaks compatibility; a minor release only adds, never removes, renames or tightens, and a tightening is a major release |
93
+ | Publishing | the `id` is a persistent-identifier namespace the project controls. Every module is served at `<id>/schema/<module>.yaml`, and a merged import-free file at `<id>/<name>.yaml`. An importer vendors a tag or imports by the identifier, never by a code-host URL, and an `importmap` bridges a path that differs |
94
+ | Annotation values | strings by default. A nested YAML value (LinkML 1.6+) is used only when a comment names the consumer that parses it, since generators ignore annotations. A fact the metamodel has no metaslot for goes in a structured annotation that the schema declares as a metamodel extension (`instantiates:`), not in a description |
95
+ | Dublin Core prefix | `dcterms: http://purl.org/dc/terms/` |
96
+ | Identity versus mappings | `class_uri` and `slot_uri` use the schema's own prefix (they render as the element's IRI); an upstream term goes in `exact_mappings` or `close_mappings` |
97
+ | Mappings | never guessed; a term with no sure match stays unmapped, or takes `related_mappings` with a comment |
98
+ | Deprecation | `deprecated:` with a reason, and `deprecated_element_has_exact_replacement:` when one exists; nothing is deleted while data may still carry it |
99
+ | Refactoring | offered when the schema folder's history is one or two people, never done unasked; a slot one class uses becomes its attribute, modules split or merge, IRIs are pinned first; a slot, value or designator rename is a major release |
100
+ | Generated files | never edited; regenerate |
101
+ | An lmodel project | [references/lmodel-profile.md](references/lmodel-profile.md), opted into by the project's own conventions, never assumed |
102
+
103
+ ## Evolving the model
104
+
105
+ - **Add** a class, slot, enum or type by the patterns in [references/metamodel.md](references/metamodel.md); then the gate.
106
+ - **Change** a range or cardinality only in the direction the existing data allows; a narrowing is a major-version change and goes with a counter-example that shows what it now rejects.
107
+ - **Rename** by adding the new element, marking the old one deprecated with its replacement, and removing the old one in a later release.
108
+ - **Split** a growing schema into modules under the same folder, imported by the main file (`imports: [./module]`), without redeclaring an imported element; a core and topic modules under an umbrella is the shape importers can take a slice of ([references/schema-design.md](references/schema-design.md)).
109
+ - **Refactor** only on offer and on a yes: fold a single-class slot into its attribute, split or merge modules, pin the IRIs; a rename goes the deprecation route above.
110
+ - **Publish** a release: the tag, the merged file beside the modules (`just merged` in a project linkml-sidecar made), their addresses and the asset ([references/publishing.md](references/publishing.md)); the hand-off names the address importers use.
111
+ - **Update the template** with `just update` on a clean tree, then the gate, then commit `uv.lock` and `.copier-answers.yml` with the diff.
112
+
113
+ ## Beside a KTL bundle
114
+
115
+ A LinkML project and a `.lokf/` bundle are separate things. The project's schema is a *domain schema*: it models the domain, stays where the project keeps it (`.linkml/src/<slug>/schema/`, or `src/<slug>/schema/` at the root) and imports nothing from `.lokf/`. A bundle's *domain vocabulary* sits in `.lokf/schema/` and may draw on several published schemas, from this repository or any other, or on none, and ktl-librarian builds it with `lokf adapt` ([domain-vocabulary.md](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/main/skills/ktl-librarian/references/domain-vocabulary.md)). So this skill's part ends at a published release: a tag, and the merged file that `just merged` writes in a project linkml-sidecar made ([references/publishing.md](references/publishing.md)). A `project.justfile` that carries `lokf-adapt` recipes, from an older linkml-sidecar, is the host's own: run them only when the person asks.
116
+
117
+ ## Hand-off
118
+
119
+ After a change, tell the person:
120
+
121
+ - which layout Step 0 found and which tools ran, and through uvx, which LinkML version;
122
+ - which elements were added, changed or deprecated;
123
+ - what the `authors` line said, and which refactoring moves were offered or made;
124
+ - what was guessed, and from which source;
125
+ - whether the gate passed;
126
+ - which docs pages were updated;
127
+ - what is left for linkml-sidecar: a broken sidecar file, or a schema that could be adopted;
128
+ - beside a `.lokf/` bundle, which file there the person named, if any, and that ktl-librarian adapts a published release into the bundle's vocabulary.