field-agent-documentation

Comprehensive template and guidelines for documenting Field Agents including technical specifications, system prompts, tool specifications, user interactions, and standardized documentation structure

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 ./field-agent-skills/documentation/SKILL.md

Quality

Content

63%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 content is a well-organized, actionable template library with a clear section sequence, but it is a monolithic single file with notable redundancy and over-explanation of basics, which hurts both conciseness and progressive disclosure.

Suggestions

Move the reference material (model selection guide, temperature guide, tool-naming quick reference, and the complete worked example) into separate files under references/ and link to them from SKILL.md to enable progressive disclosure.

Remove redundancy: delete the Quick Reference tool-naming table and the Do's/Don'ts summary since both restate Section 8 guidance, and trim the Complete Documentation Example to only what is not already shown.

Cut explanations of concepts Claude already knows (e.g. what temperature values mean, what semantic versioning is) and keep only the skill-specific recommendations.

Dimension	Reasoning	Score
Conciseness	The body is mostly useful templates, but at ~940 lines it repeats material (tool-naming good/bad examples reappear as a Quick Reference table, the Complete Documentation Example re-demonstrates earlier sections, and a Do's/Don'ts summary restates prior guidance), and explains basics Claude already knows (e.g. what temperature 0 vs 1 means).	3 / 5
Actionability	Copy-paste-ready markdown templates and worked examples (RFM segmentation agent, sample conversations, good/bad tool names) give concrete, fill-in-the-blank guidance; as an instruction/template skill the absence of executable code is not penalized, though placeholders like [Agent Name] keep it just short of fully copy-paste ready.	4 / 5
Workflow Clarity	A clear ordered 13-section documentation structure is laid out up front, and templates include checklists (prerequisites, validation items) that act as checkpoints; it is not a 5 because there is no explicit validate-then-fix feedback loop for the documentation process itself.	4 / 5
Progressive Disclosure	No bundle files exist and all content lives in one ~940-line SKILL.md; section headers provide structure, but material that clearly belongs in separate reference files (model/temperature guides, complete example, tool-naming reference) is inlined rather than split out, matching the 'content that should be separate is inline' anchor.	3 / 5
	Total	14 / 20 Passed

Description

58%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 what the skill provides and targets a specific niche, but it omits any explicit 'when to use' trigger guidance and lacks natural user-side trigger phrases, capping both completeness and trigger quality.

Suggestions

Add an explicit trigger clause, e.g. 'Use when creating or standardizing documentation for a Field Agent, writing its system prompt, or defining tool specifications.'

Include more natural user phrasings and synonyms (e.g. 'agent docs', 'agent spec', 'write system prompt') alongside the technical terms to improve trigger matching.

Lead with the concrete action verbs (e.g. 'Templates and guides for writing...') rather than the generic 'Comprehensive template and guidelines' opener.

Dimension	Reasoning	Score
Specificity	Lists several concrete documentation areas ('technical specifications, system prompts, tool specifications, user interactions, and standardized documentation structure') rather than vague abstractions, though the single verb 'documenting' means coverage is broad rather than a set of distinct actions.	4 / 5
Completeness	The 'what' is clear (a template/guidelines for documenting Field Agents), but there is no 'Use when...' clause or equivalent explicit trigger guidance, so per the rubric completeness is capped at 3.	3 / 5
Trigger Term Quality	Relevant terms like 'documenting', 'Field Agents', 'system prompts', and 'tool specifications' appear, but natural user phrasings and synonyms (e.g. 'write docs for an agent', 'agent spec') are missing, keeping it at 'some relevant keywords' rather than strong coverage.	3 / 5
Distinctiveness Conflict Risk	The niche ('documenting Field Agents') is specific and the listed components narrow the scope, leaving only minor overlap risk with general documentation skills; it is not a 5 because 'documentation' skills broadly could still compete.	4 / 5
	Total	14 / 20 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
skill_md_line_count	SKILL.md is long (942 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: treasure-data/td-skills
Path: field-agent-skills/documentation/SKILL.md
Commit: 1a0845f

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