Skip to main content
Glama

Rokha

by ai.rokha
OverviewDiscussionsAdmin

Author an Agent Skill (SKILL.md)

skill_author

Author a standard agentskills.io Agent Skill and get back its SKILL.md. A strong skill has: a name in kebab-case (lowercase letters, numbers, single hyphens, ≤64 chars); a description stating WHAT it does AND WHEN to use it, third person, with concrete trigger words (the field agents read to decide whether to load it); and instructions (the Markdown body), specific + imperative, ideally shaped When-to-use → Instructions → Examples → Guidelines. Optional compatibility (runtime/environment requirements, ≤500 chars — set when the skill needs system packages, a language version, network access, or scripts; omit for pure-instruction skills), allowed_tools (a SPACE-separated, least-privilege allowlist with optional scoping, e.g. 'Bash(git:*) Read'), license (a license name or file reference), and metadata (an object of string→string pairs). Returns the assembled SKILL.md to save as SKILL.md in a folder named after the skill. (In the Rokha UI the same tool fills the human's live builder form.)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesSkill id + folder name. kebab-case, ≤64 chars.
licenseNoOptional. A license name or bundled-file reference (e.g. 'MIT').
metadataNoOptional. Arbitrary string→string metadata (e.g. {"author":"example-org","version":"1.0"}).
descriptionYesWhat it does + when to use it. Third person, with trigger words. ≤1024 chars.
instructionsYesThe Markdown body. Specific + imperative. When-to-use → Instructions → Examples → Guidelines.
allowed_toolsNoOptional. SPACE-separated, least-privilege tool allowlist with optional scoping (e.g. 'Bash(git:*) Read'). Experimental.
compatibilityNoOptional, ≤500 chars. Runtime/environment requirements (e.g. 'Requires Python 3.14+ and uv'). Omit for pure-instruction skills.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's extra behavior is the key value: it states that the tool returns the assembled SKILL.md rather than persisting it ('to save as SKILL.md'), and it notes the Rokha UI integration. This gives the agent an accurate model of the tool's side effects without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then organized around the skill's fields with concrete constraints and examples. It is longer than average, but nearly every clause earns its place because the tool's job is to produce a standards-compliant skill, making the guidance directly actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by explaining what the tool returns and what to do next: save the output as SKILL.md in a folder named after the skill. It also covers all required and optional inputs, including when to omit compatibility, making it complete for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial meaning: kebab-case naming constraints, trigger-word and third-person requirements for description, structural guidance for instructions, when to set compatibility, and the SPACE-separated least-privilege format for allowed_tools with an example. These details go well beyond the schema's short field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Author a standard agentskills.io Agent Skill and get back its SKILL.md.' It clearly distinguishes this tool from the sibling get/search/list/read skill tools because 'author' is the creation action and the output is the assembled SKILL.md.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is clear: this tool is for authoring an Agent Skill and returning its SKILL.md. The detailed guidance on constructing name, description, instructions, and optional fields tells the agent how to invoke it confidently, though it does not explicitly name when-not-to-use alternatives like get_skill or search_skills.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Rokha toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources