Agent Skills › langwatch/langwatch › agent-best-practices

agent-best-practices

GitHub

作为AI工程顾问，审计Agent代码、追踪及评估体系，对比最佳实践发现差距。优先修复可观测性、提示词管理等基础问题，并指导深入优化，提升Agent工程质量。

skills/_compiled/native/agent-best-practices/SKILL.md langwatch/langwatch

Trigger Scenarios

希望提升Agent开发质量需要全面审计Agent工程实践寻求最佳实践改进建议

Install

npx skills add langwatch/langwatch --skill agent-best-practices -g -y

More Options

Non-standard path

npx skills add https://github.com/langwatch/langwatch/tree/main/skills/_compiled/native/agent-best-practices -g -y

Use without installing

npx skills use langwatch/langwatch@agent-best-practices

指定 Agent (Claude Code)

npx skills add langwatch/langwatch --skill agent-best-practices -a claude-code -g -y

安装 repo 全部 skill

npx skills add langwatch/langwatch --all -g -y

预览 repo 内 skill

npx skills add langwatch/langwatch --list

SKILL.md

Frontmatter

{
    "name": "agent-best-practices",
    "license": "MIT",
    "metadata": {
        "category": "recipe"
    },
    "description": "Expert AI engineering consultant for your agent development practices. Audits your codebase, traces, evaluations, and scenarios against best practices, then guides you to close the gaps, starting from low-hanging fruit and going deeper. Use when you want to level up your agent's engineering quality.",
    "user-prompt": "Where can I improve our agent development best practices?",
    "compatibility": "Requires the `langwatch` CLI with a valid `LANGWATCH_API_KEY`. Works with Claude Code and similar coding agents."
}

Improve Your Agent Development Best Practices

This recipe acts as your expert AI engineering consultant. It audits how your team builds and operates the agent, compares it against best practices, delivers quick fixes, then guides you deeper.

Phase 1: Full Audit

Before suggesting anything, read EVERYTHING:

Code Audit

Read the full codebase: every file, every function, every system prompt
Study git log --oneline -50 and read commit messages for WHY things changed. Bug fixes reveal edge cases. Refactors reveal design decisions. These are goldmines for what to test and evaluate.
Read README, docs, comments for domain context

LangWatch Audit (via CLI)

langwatch trace search --limit 25 --format json to check trace quality (inputs/outputs populated? spans connected? labels present?)
langwatch scenario list --format json to see what scenarios exist. Are they comprehensive or shallow?
langwatch suite list --format json to see what suites (run plans) exist
langwatch evaluator list --format json to see what evaluators are configured
langwatch monitor list --format json to check for online evaluation monitors
langwatch prompt list --format json to check whether prompts are versioned (or all hardcoded in code)
langwatch analytics query --metric trace-count --format json and --metric total-cost, --metric avg-latency, --metric eval-pass-rate (each with --format json) for the current cost, latency, and error/pass rate baseline

Gap Analysis

Score the setup against the best-practices checklist:

Observability: traces flowing, inputs/outputs populated, spans connected, metadata and labels present
Prompt management: prompts versioned and reviewable, not hardcoded strings scattered in code
Testing: scenario tests exist, cover the agent's real jobs and edge cases, run in CI
Evaluation: evaluators measure the qualities that matter for the domain, datasets are domain-specific, not generic
Production monitoring: online monitors watch quality signals on live traffic
Iteration loop: experiments compare changes before they ship

Identify what's missing entirely, what exists but is weak, and what's working well (keep and build on).

Phase 2: Low-Hanging Fruit

Fix the easiest, highest-impact gaps first:

Broken instrumentation: fix traces (see the debug-instrumentation recipe)
Hardcoded prompts: set up prompt versioning (langwatch prompt init, see the prompts skill)
No tests at all: create initial scenario tests (see the scenarios skill)
Generic datasets: generate domain-specific ones (see the datasets skill)

Deliver working results. Show the user what improved.

Phase 3: Guide Deeper

After Phase 2, DON'T STOP. Suggest 2-3 specific improvements based on what you learned:

Domain-specific improvements: Based on the codebase domain, suggest targeted scenarios or evaluations. "I noticed your agent handles [X], should I add edge case tests for [Y]?"
Expert involvement: If the domain is specialized (medical, financial, legal), suggest involving domain experts. "For healthcare scenarios, you'd benefit from a medical professional reviewing the compliance criteria, want me to draft scenarios they can review?"
Data quality: If using synthetic data, suggest real data. "Do you have real customer queries or support tickets? Those would make much better evaluation datasets."
CI/CD integration: If no CI pipeline, suggest adding experiments. "Want me to set up experiments that run in CI to catch regressions?"
Production monitoring: If no online evaluation, suggest monitors. "Your traces show no quality monitoring, want me to set up faithfulness checks on production traffic with langwatch monitor create?"
Learn from production: If traces show real traffic, hand over to the production-insight skills: run /agent-performance for a full diagnosis of how the agent behaves in production, and /agent-improve to turn those findings into tested changes.

Ask light questions with options. Don't overwhelm: pick the top 2-3 most impactful.

Phase 4: Keep Iterating

After each improvement:

Show what was accomplished
Run any tests / re-query analytics to verify (langwatch trace search, langwatch suite run --wait, etc.)
Ask what to tackle next
Stop when the user says "that's enough"

Common Mistakes

Do NOT skip the audit; you can't suggest improvements without understanding the current state
Do NOT give generic advice; every suggestion must be specific to this codebase
Do NOT overwhelm with 10 suggestions; pick the top 2-3
Do NOT skip running/verifying improvements