Laguagu Agents Best Practices Improving Skills

Improving Skills — Audit & Optimization Guide

Structured workflow for auditing and improving agent skills, instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), and cross-platform compatibility.

Quick audit (5 minutes)

1. Read the skill's SKILL.md and list all files in the directory
2. Check frontmatter against the specification (Step 2 below) Automated: run skills-ref validate <skill-path> if installed (reference implementation for demonstration — agentskills/skills-ref).
3. Evaluate description quality (trigger coverage, third person, specificity)
4. Scan content for anti-patterns (see anti-patterns.md)
5. Generate a prioritized improvement report (Step 5 template)

Full audit workflow

Step 1: Inventory the skill

Read the complete skill directory structure and all files.

Record:

• Total files and directories
• SKILL.md line count
• Number of reference files and scripts
• Any unusual files or structures

Step 2: Specification compliance

If skills-ref is installed, run skills-ref validate <skill-path> first to catch mechanical violations automatically. Focus manual review on description quality and content.

Frontmatter validation

• name field:
  • 1–64 characters, lowercase a-z/0-9/hyphens
  • No leading/trailing/consecutive hyphens
  • Matches parent directory name exactly
• description field:
  • 1–1024 characters, non-empty
  • Third person, imperative framing
  • Describes what the skill does AND when to use it
  • Includes trigger keywords and non-obvious activation contexts
• Optional spec fields (if present):
  • compatibility — 1–500 chars, platform/environment requirements
  • allowed-tools — space-separated pre-approved tools (Experimental)
  • license — reasonable format
  • metadata — arbitrary key-value pairs (put version here, not at root)
• Client-specific extensions (not in agentskills.io spec — silently ignored by other clients):
  • argument-hint — Claude Code: shown in skill list, helps users provide input
  • model — Claude Code: pin a model (opus | sonnet | haiku | inherit)

Structure validation

• SKILL.md exists at skill root
• SKILL.md body under 500 lines (~5,000 tokens)
• File references use relative paths with forward slashes
• All referenced files actually exist
• No deeply nested reference chains (A → B → C)
• Flat layout preferred — supporting files (e.g. anti-patterns.md) live next to SKILL.md by default
• references/ subdirectory used only when there are many files OR a separate scripts/ folder already justifies subdirectory structure

Step 3: Description quality assessment

The description is the routing key — it determines whether the skill triggers.

Trigger coverage

• Specific keywords users would say
• Non-obvious trigger contexts ("even if they don't mention X")
• Concrete use cases, not abstract capabilities
• Distinguishes this skill from adjacent/similar skills

Writing quality

• Third person only ("Processes files" not "I process files")
• Imperative framing ("Use when...")
• Focused on user intent, not implementation details
• "Pushy" enough — agents tend to under-trigger

Common description problems

Scoring (1–5)

• 5: Specific, pushy, great keyword coverage, clear trigger contexts
• 4: Good but missing one or two trigger contexts
• 3: Adequate but could be more specific or pushy
• 2: Vague or missing trigger contexts
• 1: Too generic, wrong person, or misleading

Step 4: Content quality review

Conciseness

• No explanations of things the agent already knows
• No redundant general concepts (what PDFs are, how HTTP works)
• Every piece of content justifies its token cost
• Instructions in imperative form ("Run X", "Check Y")
• No boilerplate code the agent can write from first principles — specify the contract (what it must do) not a 30-line implementation
• Framework-level adapters (AI SDK, LangChain, etc.) referenced before showing custom implementations

Progressive disclosure

• Core instructions in SKILL.md, detailed reference in separate files
• References clearly signposted with "when to read" guidance
• Large reference files (>100 lines) have table of contents
• Flat layout by default (sibling files next to SKILL.md); only group under references/ when there are many files or scripts/ already exists

Specificity calibration

• High-freedom for flexible tasks (reviews, writing)
• Low-freedom for fragile operations (migrations, destructive ops)
• Reasoning explained ("Do X because Y") rather than rigid "ALWAYS/NEVER"

Anti-patterns (quick scan)

See anti-patterns.md for full list.

• No time-sensitive information (dates, versions that go stale)
• No pinned version numbers in fast-moving domains (ML models, SDK versions, pricing) — use categories with "examples (may change — verify)" labels
• No operational/billing setup (payment methods, dashboard clicks, account creation) — link to provider docs instead
• No provider bias when multiple mainstream options exist ("best option" claims, asymmetric SDK depth across providers)
• Consistent terminology throughout
• No Windows-style backslash paths
• No unexplained magic constants
• Defaults provided (not menus of equal options)
• If skill has scripts: errors handled explicitly, not punted to agent
• Validation loops present for critical operations

Step 5: Generate improvement report

# Skill Audit Report: [skill-name]

## Summary
- Specification compliance: [PASS/FAIL with count]
- Description quality: [score/5]
- Content quality: [HIGH/MEDIUM/LOW]
- Cross-platform: [status]
- Overall: [number] issues found

## Critical issues (fix immediately)
1. [Issue]: [What's wrong] → [How to fix]

## Recommended improvements
1. [Issue]: [What's wrong] → [How to fix]

## Minor suggestions
1. [Suggestion]

## Description recommendation
Current:
> [current description]

Suggested:
> [improved description]

Batch audit

Default target: ~/.agents/skills/ (user-scope global skills). For repo-scope: .agents/skills/ relative to project root.

1. List all skill directories in the target path
2. Run Quick Audit (Steps 1–5) for each skill
3. Compile summary table:

| Skill | Spec | Description | Content | Issues |
|-------|------|-------------|---------|--------|
| skill-a | PASS | 4/5 | HIGH | 1 |
| skill-b | FAIL | 2/5 | LOW | 5 |

4. Prioritize fixes across all skills by impact

Instruction file audit

Audit agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md, etc.) for quality and consistency. These rules apply universally — every instruction file follows the same principles regardless of platform.

Universal checklist

• Exists and is not empty
• Under ~100 lines (move specialized content to skills if longer)
• Concise — every line must pass: "Would removing this cause mistakes?" If not, cut it
• No decorative project header or adapter boilerplate at the top — rules start on line 1
• Contains only rules agents can't infer from code
• No content that should be a skill (workflows, checklists, multi-step procedures)
• Gotchas section present (highest-value content)
• No stale information (outdated commands, removed tools)
• No rigid ALWAYS/NEVER without reasoning
• If agent ignores a rule → file is probably too long, not the rule too weak
• If agent asks questions answered in the file → phrasing may be ambiguous
• Emphasis (IMPORTANT, YOU MUST) used sparingly for critical rules

Should include

• Bash commands the agent can't guess
• Code style rules that differ from defaults
• Testing instructions and preferred test runners
• Repo etiquette (branch naming, PR conventions)
• Architecture decisions specific to the project
• Developer environment quirks (required env vars)
• Common gotchas and non-obvious behaviors

Should NOT include

• Anything the agent can figure out by reading code
• Standard language conventions the agent already knows
• Detailed API documentation (link to docs instead)
• Information that changes frequently
• Long explanations or tutorials
• File-by-file descriptions of the codebase
• Self-evident practices like "write clean code"

The one-line test

For every line: "Would removing this cause the agent to make mistakes?" If not, cut it. If the agent ignores a rule, the file is probably too long — not the rule too weak. If the agent asks questions answered in the file, the phrasing is ambiguous.

Platform-specific adapters

• AGENTS.md is the canonical, vendor-neutral instruction file
• Adapters (CLAUDE.md, GEMINI.md, etc.) import shared instructions via @-imports (e.g., @AGENTS.md) and add only platform-specific rules
• No duplicated content across files — shared rules belong in AGENTS.md

Skills vs. instruction files

Instruction files load every session. Skills load on demand.

• Persistent broad rule (style, testing, deploy) → instruction file
• On-demand expertise, workflow, checklist → skill
• Content only relevant sometimes → skill (not instruction file)
• If instruction file grows past ~100 lines → migrate workflows to skills

Cross-agent compatibility review

Platform discovery paths

The agentskills.io spec is client-agnostic — discovery paths are not part of the spec. The locations below are each client's own convention.

Share one skill set across all three by keeping files in ~/.agents/skills/ — Codex and Gemini pick it up natively — and junction (Windows) or symlink (macOS/Linux) ~/.claude/skills/ → ~/.agents/skills/ so Claude Code sees the same files under its own path. A working pattern: a small Python or PowerShell script that calls mklink /J (Windows) or os.symlink (POSIX) per skill directory; run once per machine setup so new skills under ~/.agents/skills/ are picked up by Claude Code through the junction.

Compatibility checklist

• Forward slashes in all paths
• Prerequisites stated explicitly
• MCP tools use fully qualified names (Server:tool_name)
• Dependency versions pinned
• No interactive prompts in scripts
• No platform-specific assumptions without compatibility field

Description rewriting

The description is the routing key — agents load only name + description at startup, so fix this first when a skill under-triggers. Third person, imperative ("Use when…"), pushy about trigger contexts, under 1024 characters.

For full trigger evaluation (build a query set, grade with a validation split, iterate), use the skill-creator skill — that's where the benchmark tooling lives. This skill stops at identifying that a rewrite is needed.

Gotchas

• description has a hard cap of 1024 characters — count characters before saving when writing long descriptions
• name must match the directory name exactly — uppercase letters, underscores, or spaces break discovery
• In batch audits, ~/.agents/skills/ is the user-scope default, .agents/skills/ is repo-scope — don't mix them up
• Symlinks from .claude/skills/ → .agents/skills/ can cause duplicate discovery reports
• Instruction file audit (AGENTS.md/CLAUDE.md) is a separate workflow from skill audit — don't combine them into the same report
• allowed-tools is marked Experimental in the spec — don't add routinely, support varies across platforms
• version is not a root-level frontmatter field — to version a skill, place it under metadata: { version: "1.0" }. Free-form root-level keys may be rejected by spec validators
• argument-hint and model are Claude Code -specific extensions, not in agentskills.io spec — other clients silently ignore them. Safe to use, but don't rely on cross-client behavior
• Root skills/ breaks discovery: Moving project skills from .agents/skills/ to a root skills/ directory breaks Claude Code /skills discovery and Codex auto-discovery — both scan .agents/skills/ (repo scope) directly. Root skills/ only works as AGENTS.md @include context, not as a discoverable/invokable skill. Keep skills in .agents/skills/<name>/. To auto-load a skill every session, add @.agents/skills/<name>/SKILL.md to AGENTS.md.
• Verify behavioral claims against official docs/source before editing — truncation behavior, deprecation status, experimental flags, and token budgets must come from specs, READMEs, or source code, not from inference or plausibility. When docs are silent on a behavior, preserve the original wording rather than invent it. A plausible-sounding claim that rots later is worse than no claim.

The goal is reliable triggering, specification compliance, and clear value without wasting context tokens.

Source: laguagu/agents-best-practices — distributed by TomeVault.