Is canonical-repo-structure safe to install?

SaferSkills independently audited canonical-repo-structure (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

skills/software-engineering-method/canonical-repo-structure/SKILL.md · 1 file

skills/software-engineering-method/canonical-repo-structure/SKILL.md18.6 KB · Markdown

# name: stable kebab-case skill identifier; must match the parent directory.

name: canonical-repo-structure

# description: routing contract for when this skill should activate and when it should not.

description: "Use when organizing or cleaning a project/repository so every script, command, prompt, doc, generated artifact, compatibility shim, and legacy path has one canonical home under version control. Covers owner selection, repo-boundary verification, generated-vs-authored separation, duplicate implementation cleanup, compatibility-shim registration, delete-to-git-history discipline, timestamped changelog explanations, and path-limited commits in the owning repo. Do NOT use for ordinary branching/rebase/tag strategy alone (use `version-control`), behavior-preserving code restructuring alone (use `refactor`), documentation-sync routing alone (use `doc-updater`), or controlled category taxonomy design alone (use `taxonomy-design`)."

# license: SPDX-compatible license identifier for the skill content.

license: MIT

# compatibility: runtime compatibility notes for consumers.

compatibility:

notes: "Project-structure governance for multi-repo workspaces with git history, generated artifacts, and runtime compatibility paths."

# allowed-tools: optional runtime hint for tools the skill may use when loaded.

allowed-tools: Read Grep Bash Edit

# metadata: Skill Metadata Protocol fields encoded under Agent Skills-compatible frontmatter.

metadata:

# subject: primary browse shelf - the competency the skill teaches. One of twelve closed values:

# backend-engineering / frontend-engineering / software-architecture / data-engineering /

# agent-ops / ai-engineering / quality-assurance / design / reasoning-strategy /

# software-engineering-method / knowledge-organization / product-domain.

subject: software-engineering-method

# subjects: optional polyhierarchy. Max 2 entries; primary subject first.

subjects: "[\"software-engineering-method\",\"knowledge-organization\"]"

# public: publishability / private-data gate. true = safe for public release; false = private/internal.

# Project anchoring lives in project[] and requires grounding when present.

# project: projects this skill is linked to. Array of {handle, role} objects.

project: "[{\"handle\":\"development\",\"role\":\"source-of-truth\"},{\"handle\":\"skill-graph\",\"role\":\"source-of-truth\"},{\"handle\":\"skills\",\"role\":\"canonical-skill-library\"}]"

# scope: required PRD-style free-text statement of what the skill teaches and what it does not.

scope: "Organizing a project or repository into one canonical, version-controlled structure: choose the owning repo and path, separate authored source from generated output, register only necessary compatibility shims, delete confirmed-dead legacy code to git history with a timestamped changelog explanation, update live references, and commit path-limited in the owning repo. Project-targeted to the Development workspace and Skill Graph doctrine, but written as a reusable method for controlled repos. Excludes ordinary git branching/rebase/tag strategy, behavior-preserving code refactors without ownership changes, documentation-sync routing alone, and controlled taxonomy design alone."

# public: publishability / private-data gate. true = safe for public release; false = private/internal.

public: false

# taxonomy_domain: optional hierarchical sub-path within `subject`.

# Slash-delimited lowercase kebab-case segments.

taxonomy_domain: engineering/repository-governance

# stability: lifecycle marker. One of:

# experimental (active development) / stable (production-ready) /

# frozen (no further changes expected) / deprecated.

stability: experimental

# keywords: semantic phrases for fuzzy router activation. v8 cap: max 10.

keywords: ["canonical repo structure","project structure","repository organization","canonical owner","implementation ownership","compatibility shim","delete dont archive","legacy cleanup","generated artifact","path-limited commit"]

# examples: realistic user prompts the skill SHOULD activate for.

examples: ["organize this repo so every script and command has one canonical home","we have a duplicate command in .claude, .opencode, and skill-graph - which one stays?","clean up legacy scripts without leaving an _archive folder","move this implementation to the owning repo and leave only the runtime shim","before deleting this old migration script, what evidence do I need?","make this project structure canonical and version-controlled","this generated output is being hand-edited - fix the repo structure","where should this new cross-repo helper live so it does not become bloat?"]

# anti_examples: near-miss prompts that should route ELSEWHERE.

anti_examples: ["should I rebase or merge this feature branch?","split this 600-line module into smaller functions without changing behavior","update the docs for this API change in the same commit","design a category tree for these skills","write a Conventional Commits message for this patch","audit this PR for security and correctness"]

# paths: file surfaces where this skill should be considered.

paths: "[\"AGENTS.md\",\"CLAUDE.md\",\"CONTEXT.md\",\"docs/reference/implementation-ownership.md\",\"docs/reference/implementation-ownership.json\",\"docs/reference/artifact-lifecycle-contract.md\",\"docs/reference/runtime-compatibility-boundary.md\",\".claude/rules/delete-dont-archive.md\",\"skill-graph/AGENTS.md\",\"skill-graph/SKILL_GRAPH.md\",\"skill-graph/CHANGELOG.md\",\"skill-graph/docs/adr/*.md\",\"skill-graph/scripts/**\",\"skill-graph/lib/**\",\"skill-graph/bin/**\",\"skill-graph/prompts/**\",\"skills/skills/**/SKILL.md\",\"skills/skills/**/audit-state.json\"]"

# relations: typed graph edges to sibling skills.

# related (adjacency) / boundary (exclude target when THIS skill wins) /

# verify_with (cross-check) / depends_on / broader / narrower / disjoint_with.

# grounding: required for project-targeted skills. Declares truth sources and failure modes.

grounding: "{\"subject_matter\":\"Canonical project and repository organization in the Development workspace and Skill Graph project\",\"grounding_mode\":\"repo_specific\",\"truth_sources\":[\"AGENTS.md\",\"CLAUDE.md\",\"CONTEXT.md\",\"docs/reference/implementation-ownership.md\",\"docs/reference/artifact-lifecycle-contract.md\",\"docs/reference/documentation-standards.md\",\".claude/rules/delete-dont-archive.md\",\".claude/rules/version-schema-contract.md\",\"skill-graph/AGENTS.md\",\"skill-graph/SKILL_GRAPH.md\",\"skill-graph/CONTRIBUTING.md\",\"skill-graph/docs/quality-doctrine.md\"],\"failure_modes\":[\"duplicate_implementation_preserved\",\"generated_output_hand_edited\",\"legacy_path_left_unregistered\",\"dead_code_archived_in_tree\",\"deletion_without_recovery_path\",\"stale_live_reference_after_move\",\"wrong_repo_commit\",\"version_label_bumped_without_content\",\"compatibility_shim_contains_logic\",\"timestamp_without_time_of_day\"],\"evidence_priority\":\"repo_code_first\"}"

# mental_model: primitives of the concept and how they relate.

mental_model: "A repository is a map of ownership. Each artifact has one canonical source, zero or more generated projections, and at most one compatibility path per runtime that truly needs the old entrypoint. Git history is the archive for confirmed-dead code; live docs and registries are the map that tells future agents where the current artifact lives."

# purpose: problem this concept solves.

purpose: "Prevents repository bloat from accumulating as duplicate scripts, stale command bodies, archived folders, generated files treated as source, and undocumented legacy paths. The skill turns cleanup into an evidence-backed workflow: find the owner, verify live references, choose source vs generated vs shim vs delete, record why, and commit only the owned paths."

# boundary: what this concept is NOT.

concept_boundary: "This skill is not ordinary git workflow design, code refactoring, documentation-writing technique, taxonomy design, or full PR review. It decides where artifacts belong, whether a legacy path is still live, whether a compatibility shim is justified, and how confirmed-dead version-controlled code leaves the tree without becoming an archive folder."

# analogy: one-sentence metaphor preserving the core mechanism.

analogy: "A canonical repository structure is like a city records office: every property has one deed, maps can point to it, and old addresses are kept in the historical register instead of painted on abandoned buildings."

# misconception: wrong mental model corrected explicitly.

misconception: "The common mistake is treating cleanup as moving old files into an archive directory. That preserves the cost while hiding the decision; confirmed-dead code belongs in git history with the reason and recovery command recorded, while live compatibility paths must be registered shims with no duplicated logic."

# relations: typed graph edges to sibling skills.

relations:

related: ["taxonomy-design","skill-infrastructure","semantics","information-architecture","version-control","doc-updater","refactor","naming-conventions","methodical","no-cutting-corners"]

suppresses: ["refactor","version-control"]

verify_with: ["doc-updater","naming-conventions","methodical","no-cutting-corners","version-control"]

Canonical Repo Structure

Concept of the skill

A repository is a map of ownership. Each artifact has one canonical source, zero or more generated projections, and at most one compatibility path per runtime that truly needs the old entrypoint.

Coverage

Choosing the owning repo and canonical path before creating, moving, or deleting scripts, commands, prompts, docs, generated artifacts, skills, and compatibility entrypoints
Separating authored source from generated projections so agents edit the real source and regenerate the output
Preventing duplicate implementations: update the owner, convert one necessary compatibility path into a thin registered shim, or remove the extra path
Deciding whether a legacy artifact is live, deprecated, confirmed dead, generated, historical, or a runtime-required compatibility entrypoint
Deleting confirmed-dead code to git history instead of preserving _archive/, .legacy, commented-out blocks, or "kept just in case" copies
Recording deprecation/removal reasons in the owning changelog with a date plus time-of-day when the owning repo requires timestamped prose
Updating live references after moves/deletions while leaving frozen historical records accurate
Committing path-limited in the repo that owns the changed files

Philosophy of the skill

A repo is not just storage. It is an operating map for future agents. When one command body lives in three places, no reader knows which behavior is real. When generated output is hand-edited, the next generation run destroys the change. When dead code is moved into _archive/, every grep, router, audit, and cold-start reader has to rediscover that the file is dead.

Canonical organization is therefore a reliability feature. The correct tree is not the smallest tree; it is the tree where source, generated output, compatibility paths, and historical records are visibly different. Preserve live capability, preserve historical recovery in git, and remove dead weight from the live working tree.

Workflow

Identify the artifact and owning repo. Run git rev-parse --show-toplevel from the path you will touch. For nested repos, commit in the nearest owning repo, not in the parent that happens to list or ignore the path.
Find existing owners before adding a new path. Search names, commands, imports, package scripts, docs, and registries. If an owner exists, update that owner instead of copying it.
Classify the path.

Authored source: human-edited truth. Keep one canonical file.
Generated projection: regenerated from source. Do not hand-edit; update the generator or source.
Compatibility path: runtime-required entrypoint that delegates to canonical source. Register it and keep it thin.
Frozen historical record: changelog, ADR, report, or archived analysis that describes past state. Do not rewrite it to pretend history changed.
Confirmed-dead artifact: no live consumer and no current contract. Remove it from the tree.

Choose the canonical home from the owner map. Use the project AGENTS.md, implementation-ownership registry, document-routing table, package entrypoints, and runtime constraints. If a runtime can only read a specific path, leave a minimal shim there and put the logic in the canonical project-owned path.
Verify before deprecating or deleting. Grep live code, docs, scripts, package files, command manifests, and routing registries. Exclude frozen historical records from the live-dependency decision. A historical mention proves the artifact existed; it does not prove the artifact is still live.
Remove confirmed-dead implementation code to git history. Use git rm for tracked files. Do not move dead code to an archive folder or leave commented-out code. Record what was removed, why it was dead, the replacement or shim target if one exists, and a recovery command such as git log --all --oneline -- <path> followed by git checkout <sha>^ -- <path>.
Update live references in the same change. Grep *.md, *.sh, *.json, package scripts, command manifests, and owning docs for the old path/name. Fix live references; leave changelog/ADR/report mentions alone unless they are themselves wrong.
Commit only the owned paths. Use path-limited commits in the repo that owns the files. If multiple repos changed, create separate commits per repo.

Placement Rules

Artifact kind	Canonical home	Compatibility rule
Project-specific system code	Owning project repo, usually under `lib/`, `scripts/`, `bin/`, or the project-specific command/prompt directory	Leave a shim only when a runtime mechanically resolves from a fixed path
Individual skill content	`skills/skills/<subject>/<skill-name>/SKILL.md` plus sibling artifacts	Do not author skill content in generated marketplace exports
Skill Graph schema, audit, prompt, and tooling system code	`skill-graph/` paths owned by the Skill Graph project	Runtime command files outside `skill-graph/` carry only pointer/delegation text when required
Generated manifests, indexes, exports, and status files	Generated by their named script	Regenerate from source; do not patch by hand unless the generator is the thing being fixed
Documentation truth	The owning doc named by the routing table	Indexes and pointer files link to the owner; they do not duplicate the body
Removed or superseded code	Git history, changelog explanation, and optional removed-path registry	No `_archive/`, `.legacy`, or commented-out implementation body in the live tree

Keep, Shim, Or Remove

Evidence	Action
Live imports, package scripts, runtime command resolution, tests, or documented user entrypoint still call the path	Keep it or convert it into a thin shim after moving logic
Path exists only for a runtime that cannot resolve the canonical location	Keep a registered shim with no business logic and a documented removal condition
Path is generated from a source file	Delete manual edits, fix source/generator, and regenerate
Only frozen historical records mention it	Remove the live artifact and leave the historical records unchanged
No live references, job complete, superseded owner wired, or one-shot migration finished	`git rm`, update changelog/registry as required, and record recovery command
You cannot prove whether it is live	Keep it for now and flag the uncertainty; do not guess-delete

Deprecation And Removal Discipline

Deprecation is caused by a replacement, direction change, or completed migration. It is not caused by age alone.
The live tree carries current source, current shims, current generated outputs, and current docs. Prior implementations live in git history.
A deprecated compatibility path that stays callable must be registered with its canonical target, status, removal condition, and required delegation/import target.
A removed implementation path should be listed in the owning removed-path registry when such a registry exists, so it is not silently resurrected.
Changelog entries for deprecation/removal name the artifact, why it changed, the replacement or shim target, and how to recover it from git.
When the owning project requires timestamped prose, use date plus time-of-day, for example 2026-06-07T14:32+02:00, not just 2026-06-07.

Verification

[ ] The nearest git repo owner was verified for every changed path
[ ] Existing owners and duplicate paths were searched before adding a new artifact
[ ] Authored source and generated projections are visibly separated
[ ] Any compatibility path is registered, minimal, and delegates to the canonical path
[ ] Confirmed-dead code was removed from the live tree rather than archived in-place
[ ] Live references to moved/deleted paths were updated; frozen historical references were left intact unless wrong
[ ] The owning changelog or lifecycle registry records deprecation/removal reason and recovery path when required
[ ] Path-limited commits were used in the owning repo, with separate commits for separate repos

Do NOT Use When

Use instead	When
`version-control`	The task is choosing branch strategy, rebase vs merge, release tags, commit boundaries, or worktree lifecycle without changing canonical artifact ownership.
`refactor`	The task is behavior-preserving code restructuring inside an already canonical implementation path.
`doc-updater`	The task is only routing a code change to its owning docs and verifying docs changed in the same commit.
`taxonomy-design`	The task is only designing categories, facets, controlled vocabularies, or classification assignment rules.
`code-review`	The task is reviewing a PR/diff holistically for bugs, security, performance, and tests.

Key Sources

AGENTS.md - repo ownership, document routing, and implementation ownership rules
docs/reference/implementation-ownership.md - canonical implementation registry and compatibility-shim contract
docs/reference/artifact-lifecycle-contract.md - lifecycle metadata and changelog discipline for non-skill artifacts
.claude/rules/delete-dont-archive.md - confirmed-dead code is deleted to git history, not archived in the tree
skill-graph/AGENTS.md - Skill Graph canonical-location rule, delete-to-git-history directive, and timestamped changelog requirement
skill-graph/SKILL_GRAPH.md - Skill Graph source vs generated marketplace distinction
docs/reference/documentation-standards.md - one canonical source per fact and generated/reference verification gates

canonical-repo-structure— agent skill

Is canonical-repo-structure safe to install?

Canonical Repo Structure

Concept of the skill

Coverage

Philosophy of the skill

Workflow

Placement Rules

Keep, Shim, Or Remove

Deprecation And Removal Discipline

Verification

Do NOT Use When

Key Sources

Audit the pieces. Scan the whole. Decide.