architect

Semantic chunker, embedding engine, and ChromaDB store. Consumes ChangeEvents from the Scout, chunks files at function/class boundaries, generates embeddings, and manages the vector store.

Quality

56%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./workspace/skills/architect/SKILL.md

Quality

Content

65%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a clean, well-structured overview that properly delegates implementation to real script files, but it stops at describing capabilities and class names rather than giving executable usage guidance or a sequenced, validated workflow for its destructive vector-store operations.

Suggestions

Add a short executable Quick start showing how to run the pipeline (e.g., a concrete pipeline.py invocation with inputs/outputs) so guidance is copy-paste ready.

Include an explicit sequenced workflow (ingest ChangeEvent -> chunk -> embed -> upsert) with a validation/checkpoint step before the destructive delete-then-insert upsert.

Show one concrete code example for the most common operation (e.g., calling VectorStore.upsert or SemanticChunker) to move from description to instruction.

Dimension	Reasoning	Score
Conciseness	Lean overview with no padding and no explanation of concepts Claude already knows; every line (Capabilities and Scripts lists) earns its place.	5 / 5
Actionability	It labels what each script contains ('SemanticChunker class', 'Embedder class (Nomic + Anthropic fallback)') but provides no executable code, commands, or concrete usage steps — it describes rather than instructs, which is minimal concrete guidance for a code skill.	2 / 5
Workflow Clarity	Only a weakly implied chunk-then-embed-then-store sequence (via pipeline.py) with no explicit steps and no validation checkpoints; destructive batch ops ('delete-then-insert', 'delete') without validation cap this at 3.	3 / 5
Progressive Disclosure	Well-organized sections with one-level-deep references to real bundle files (chunker.py, embedder.py, store.py, pipeline.py), each clearly signaled; implementation correctly lives in scripts rather than inlined.	5 / 5
	Total	15 / 20 Passed

Description

47%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description clearly states concrete capabilities in third person but is written in internal pipeline jargon with no natural trigger terms and no 'Use when...' guidance, capping completeness. It reads as an internal component summary rather than a user-invocable skill description.

Suggestions

Add an explicit 'Use when...' clause stating when Claude should invoke this skill (e.g., 'Use when processing ChangeEvents into the vector store or when embedding/chunking source files').

Replace pure jargon with natural trigger terms users would say, such as 'embed files', 'chunk source code', 'search code semantically', alongside the technical terms.

Reframe capabilities as user-facing tasks (e.g., 'Embed and store code chunks for semantic search') so the description is distinguishable from other vector-store skills.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('chunks files at function/class boundaries', 'generates embeddings', 'manages the vector store', 'Consumes ChangeEvents') with minor coverage gaps; framed internally rather than as a comprehensive user-facing capability list, so just below a 5.	4 / 5
Completeness	Has a clear 'what' but no explicit 'when' / 'Use when...' clause, so per the missing-trigger-guidance rule completeness is capped at 3; not lower because the 'what' is concrete rather than vague.	3 / 5
Trigger Term Quality	Dominated by technical jargon ('ChangeEvents', 'ChromaDB', 'function/class boundaries') that users would not naturally say; only 'embeddings' and 'vector store' are recognizable natural terms, missing common variations.	2 / 5
Distinctiveness Conflict Risk	The ChromaDB + Scout ChangeEvents + semantic chunking combination is a somewhat distinct niche but lacks distinct user-facing trigger phrases, leaving overlap risk with other embedding/vector skills.	3 / 5
	Total	12 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: tombrewsviews/repository-os-mvp
Path: workspace/skills/architect/SKILL.md
Commit: a30d1b4

Reviewed: ~20 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.