rill-rillyaml

Detailed instructions and examples for developing the rill.yaml file

Quality

61%

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 ./skills/rill-rillyaml/SKILL.md

Quality

Content

65%

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

The body is well-organized and highly actionable, with concrete copy-paste YAML examples and clear per-property explanations. Its main weaknesses are token efficiency and progressive disclosure: a large verbatim JSON schema is inlined rather than split into a reference file, and there is no explicit multi-step workflow with validation checkpoints for safely authoring rill.yaml.

Suggestions

Move the full JSON schema into a separate reference file (e.g. references/rill-yaml.schema.json) and link to it, keeping only the most-used properties inline in SKILL.md.

Add a short authoring workflow with a validation checkpoint, e.g. '1. Set required/default properties; 2. Run `rill start` to validate the project parses; 3. Fix and re-validate before deploying.'

Trim or summarize the reserved rill.* env-key list to the most common ones, linking to the schema for the exhaustive set.

Dimension	Reasoning	Score
Conciseness	The Core Concepts prose and examples are reasonably efficient, but a ~270-line verbatim JSON schema (including dozens of reserved rill.* keys with full descriptions) is inlined as padding that could be tightened or externalized, matching 'mostly efficient but could be tightened'; it is not score 1 because the schema is domain-specific reference rather than common-knowledge explanation, and not score 3 because the inlined schema bulk does not earn every token.	2 / 3
Actionability	The Minimal and Complete Examples are complete, copy-paste-ready YAML, and Core Concepts names specific properties with concrete values (duckdb, clickhouse, openai, claude, gemini), matching 'fully executable code/commands; specific examples; copy-paste ready'; it is above score 2 because the examples are concrete and usable rather than pseudocode or abstract.	3 / 3
Workflow Clarity	Sections follow a loose progression (intro -> concepts -> minimal example -> complete example -> reference) but there is no multi-step sequenced workflow with validation checkpoints for authoring rill.yaml, fitting 'sequence present but checkpoints missing'; it is not score 1 because organization is clear, and not score 3 because no explicit validation/feedback steps are given.	2 / 3
Progressive Disclosure	There are no bundle files and the entire reference, including the large JSON schema, is inlined in SKILL.md, matching 'content that should be separate is inline' with some section structure present; it is not score 1 because sections are organized rather than a monolithic wall, and not score 3 because there are no one-level-deep references to separate files.	2 / 3
	Total	9 / 12 Passed

Description

57%

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 identifies a distinct, niche target (the rill.yaml file) and states what the skill provides, but it relies on generic phrasing ('developing', 'Detailed instructions and examples') without enumerating concrete actions or an explicit 'Use when' trigger clause. It is specific enough to avoid conflicts yet too vague to fully communicate capabilities or invocation conditions.

Suggestions

Replace 'developing the rill.yaml file' with several concrete actions, e.g. 'Configure OLAP/AI connectors, set mock users for security testing, manage env variables, and define project-wide resource defaults in rill.yaml.'

Add an explicit trigger clause such as 'Use when the user is authoring or editing rill.yaml for a Rill project, or mentions Rill project configuration, OLAP/AI connectors, or mock users.'

Drop the filler word 'Detailed' to tighten the description and reduce vague padding.

Dimension	Reasoning	Score
Specificity	The phrase "developing the rill.yaml file" names a concrete domain and a loose action but does not list multiple specific concrete actions (e.g. configure OLAP connectors, set mock users, manage env vars), matching the 'names domain and some actions, but not comprehensive' anchor; it is not score 1 because the target is specific rather than abstract, and not score 3 because no enumerated concrete actions appear.	2 / 3
Completeness	It states what the skill provides ("Detailed instructions and examples for developing the rill.yaml file") but includes no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 2; it has 'what' with 'when' only implied, so it is not score 1 and cannot reach score 3.	2 / 3
Trigger Term Quality	"rill.yaml file" is a natural keyword a Rill user would say, but the description lacks common variations such as 'Rill project config' or 'Rill configuration', fitting 'some relevant keywords but missing common variations'; it is above score 1 (a genuine natural term is present) but below score 3 (no broad coverage of terms).	2 / 3
Distinctiveness Conflict Risk	"rill.yaml" is a narrow, specific artifact that users would only mention when they need this exact configuration reference, giving it a clear niche with distinct triggers unlikely to conflict with other skills; it is above score 2 because the target is unmistakably specific rather than broadly overlapping.	3 / 3
	Total	9 / 12 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 6 missing, 5 suspicious	Warning

	Total	15 / 16 Passed

Repository: rilldata/agent-skills
Path: skills/rill-rillyaml/SKILL.md
Commit: aa23a8e

Reviewed: 1 day 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.