How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/objectivlabs/reposkillopt --skill repo-architectureBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
RepoSkillOpt — As-Is Architecture Analysis (Canonical Skill)
Purpose
This is the repo-specializing analysis layer of RepoSkillOpt. The generic understanding skill (repo-skillopt) is unchanged — it produces the repo-neutral Repository Specification. This skill specializes on a specific repository: it deepens that Repository Specification into an evidence-grounded view of the current architecture and answers "what would a change ripple into?" — before anything is touched. It produces an Architecture View and a Change-Impact (blast-radius) Analysis, and is the analyze as-is stage the plan to-be skill (repo-orchestration) consumes. The skill's own content is vendor-neutral (no coding-agent runtime dependency); its output is repo-specific.
Trigger Conditions
Activate when the user asks to map the architecture, assess dependencies/coupling/layering, or evaluate "what would change if we… / is it safe to change X" — or recognizable equivalents. Do not activate for unrelated requests.
Prerequisite
A Repository Specification (.reposkillopt/specs/repository-specification.md). If absent, state the prerequisite and point the user to the repository-understanding skill; do not fabricate an architecture from shallow inspection.
Operating Principles
- Build on the spec, corroborate against code. The Repository Specification is the starting
evidence; verify every architectural claim against the actual files, configs, and call sites.
- Ground every major claim. Each carries exactly one label —
**[fact]**,**[inference]**,
**[unknown]**, **[human]**; **[fact]** MUST carry a resolvable file:line/symbol citation.
- No silent omission. Unresolvable structure or impact is
**[unknown]**with the reason, never dropped. - Do not overclaim. Do not describe layers or flows you have not traced; mark inference as inference.
- Repository facts stay repository-scoped. Only patterns explicitly marked candidate-for-generic
may enter the skill-convergence loop.
Workflow
(a) Read the Repository Specification and the entrypoints, manifests, and core modules it cites.
(b) Architecture View (.reposkillopt/architecture/architecture-view.md, per templates/architecture-view.md): C4-style levels — Context (system + external actors), Containers (runtime/deployable units), Components (modules within containers) — plus Key sequences (end-to-end flows, cited at each hop) and a Dependency graph (cited internal edges). Every component and edge cites a real file:line. Diagrams (graph, sequenceDiagram) are visual aids and carry no citations; every node/edge they show also appears as a cited line.
(c) Change-Impact Analysis (.reposkillopt/impact/change-impact-analysis.md, per templates/change-impact-analysis.md): for the named target/change, the affected modules, tests, contracts, and call sites — each row with a confidence label (high|medium|low) tied to evidence strength (direct cited call site = high; name-resolution/inference = medium; dynamic/unresolved = low and **[unknown]**) and a citation. Locate impact with a fast scanner (rg/grep) and read only the matched lines you cite.
(d) Deterministic completeness gate. Before finishing, the artifacts MUST pass the deterministic checks (check_architecture_view, check_impact_analysis): every component/edge cited and resolvable; every impact row carries a citation and a confidence label.
Output Discipline
Labels: **[fact]** (verified; cited), **[inference]** (state the basis), **[unknown]** (also listed as such), **[human]** (cite the Feedback Item id). Citations use path:line, path:start-end, path:Symbol[:line], or cmd:/output:. Trivial recitations need no label.
Human Feedback Loop
Corrections are recorded as Feedback Items (templates/human-feedback.md) under .reposkillopt/feedback/ and applied to the artifact in place. Repository-specific corrections stay repository-scoped.
Skill Convergence Loop
When recurrent feedback (≥3 related items) marked candidate-for-generic reveals a weakness in this skill, draft a Skill Edit Proposal (templates/skill-edit-proposal.md). It may be accepted only after passing the validation gate (rubric/validation-gate.md): regenerate the artifacts for a disjoint held-out reference set with no per-dimension rubric regression (see rubric/asis-architecture-rubric.md) and the deterministic checks still passing. Nothing is silently promoted; acceptance bumps the version + adds a CHANGELOG entry. Mirror every accepted edit into the four adapters (adapter-equivalence).