grounding

Establish what is actually true and current for the surface you are about to change — not just search. Grounding = locate the authoritative source and reconcile sources that disagree (code vs doc, migration vs schema, memory vs current code, live vs archived), not take the first hit. Use before any grep/find/explore of the codebase or docs, when deciding which of several definitions is the real one, or when a doc or memory conflicts with the code. Covers the source-of-truth hierarchy, reconciliation discipline, scoped ripgrep, and the docs/tags.yml + docsearch.py index.

Quality

90%

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

Quality

Content

87%

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

A lean, highly actionable reference with real bundle integration and clear sectioning. The main gap is workflow clarity: the grounding decision process is implied rather than laid out as an explicit sequenced procedure with checkpoints.

Suggestions

Add a short numbered grounding procedure (1. name the surface; 2. look up its authoritative source in the hierarchy; 3. on disagreement, decide the winner with a stated rationale; 4. verify against running code/tests before acting) to make the workflow explicit.

Add an explicit verify/checkpoint step (e.g. 'confirm what the running entrypoint actually imports before trusting a doc over code') as a validation gate before acting.

Dimension	Reasoning	Score
Conciseness	Dense, Grida-specific information Claude would not already know, with no padding about generic search concepts; the opening briefly restates the skill's own framing but otherwise every token earns its place.	3 / 3
Actionability	Provides copy-paste-ready commands (`rg PATTERN editor/grida-canvas packages`, `rg PATTERN -g '!/docs/_history/'`, `uv run $S tags/find/show`) plus concrete file paths, URLs, and a branch name, meeting the 'fully executable' anchor.	3 / 3
Workflow Clarity	The decision process (name surface → trust authority → reconcile disagreement → decide winner with rationale) is present but not sequenced as explicit steps with validation checkpoints, so it sits between the 'steps listed' and 'clear sequence with checkpoints' anchors.	2 / 3
Progressive Disclosure	Well-organized into focused sections with a real one-level-deep reference (scripts/docsearch.py, confirmed present) signaled inline with usage examples; content is appropriately kept inline for a focused skill.	3 / 3
	Total	11 / 12 Passed

Description

92%

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

A strong, third-person description with concrete actions, named tools, and an explicit 'Use when' trigger clause. Its only weakness is a somewhat broad search trigger that risks overlap with generic exploration skills.

Suggestions

Tighten the trigger to reduce overlap, e.g. 'Use before grep/find/explore when sources may disagree or a doc/memory conflicts with code' rather than any codebase search.

Lead with the distinguishing action ('reconcile disagreeing sources to find the authoritative one') before the broad search trigger to make the niche immediately clear.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('locate the authoritative source', 'reconcile sources that disagree', 'scoped ripgrep') and names specific tools (ripgrep, docs/tags.yml, docsearch.py), matching the 'multiple specific concrete actions' anchor.	3 / 3
Completeness	Explicitly answers both what (grounding = locate authoritative source and reconcile disagreements) and when (the 'Use before...' clause), meeting the 'both what AND when with explicit triggers' anchor.	3 / 3
Trigger Term Quality	The 'Use before any grep/find/explore of the codebase or docs, when deciding which of several definitions is the real one, or when a doc or memory conflicts with the code' clause gives good coverage of natural trigger phrases a user would actually say.	3 / 3
Distinctiveness Conflict Risk	The reconciliation/source-of-truth niche is distinct, but the broad trigger 'Use before any grep/find/explore of the codebase or docs' could overlap with general search/exploration skills, so it is not clearly conflict-free.	2 / 3
	Total	11 / 12 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: gridaco/grida
Path: .agents/skills/grounding/SKILL.md
Commit: 2e0d276

Reviewed: 3 days 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.