[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75901":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":9,"languages":9,"totalLinesOfCode":9,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":36,"readmeContent":37,"aiSummary":38,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":39,"discoverSource":40},75901,"agents-best-practices","DenisSergeevitch\u002Fagents-best-practices","DenisSergeevitch","Provider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.",null,1912,163,9,2,0,14,137,1116,69,104.64,"MIT License",false,"main",[24,25,26,27,28,29,30,31,32,33,34,35],"agent-skill","agent-skills","agentic-workflows","agents","ai-agents","anthropic","claude","claude-code","codex","codex-skill","mcp","prompt-engineering","2026-06-12 04:01:19","\u003Cdiv align=\"center\">\n\n# agents-best-practices\n\n\u003Cimg src=\"icon.jpeg\" alt=\"agents-best-practices icon\" width=\"300\" \u002F>\n\n> *\"The model proposes actions; the harness validates, authorizes, executes, records, and returns observations.\"*\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Agent Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAgent-Skill-7c3aed)](SKILL.md)\n[![Codex](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-compatible-111827)](SKILL.md)\n[![Claude Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-compatible-8b5cf6)](SKILL.md)\n\n\u003Cbr>\n\n**A provider-neutral Agent Skill for designing, generating MVP blueprints for, auditing, refactoring, and explaining agentic harnesses.**\n\nIt applies beyond coding agents: research, support, operations, sales, finance, data analysis, procurement, legal workflows, healthcare workflows, education, and workflow automation agents all need the same core runtime discipline.\n\n\u003Cbr>\n\n**Install** - pick one:\n\n\u003C\u002Fdiv>\n\n**A. With [`skills`](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fskills) (any compatible agent):**\n\n```bash\nnpx skills add DenisSergeevitch\u002Fagents-best-practices -g\n```\n\nThe `-g` flag installs globally at user level so every project can discover it.\n\n**B. Or paste this prompt to your AI agent:**\n\n```text\nInstall the agents-best-practices skill for me:\n\n1. Clone https:\u002F\u002Fgithub.com\u002FDenisSergeevitch\u002Fagents-best-practices into my\n   user-level skills directory as `agents-best-practices\u002F`.\n   Use the skill directory my agent reads on this machine, for example:\n   - Codex: ~\u002F.codex\u002Fskills\u002F\n   - Claude Code: ~\u002F.claude\u002Fskills\u002F\n2. Verify that SKILL.md, icon.jpeg, and the references\u002F directory are present.\n3. Confirm the install path when done.\n```\n\n**C. Manual install paths:**\n\n```bash\n# Codex\nmkdir -p \"${CODEX_HOME:-$HOME\u002F.codex}\u002Fskills\"\ngit clone https:\u002F\u002Fgithub.com\u002FDenisSergeevitch\u002Fagents-best-practices.git \\\n  \"${CODEX_HOME:-$HOME\u002F.codex}\u002Fskills\u002Fagents-best-practices\"\n\n# Claude Code, user-level\nmkdir -p \"$HOME\u002F.claude\u002Fskills\"\ngit clone https:\u002F\u002Fgithub.com\u002FDenisSergeevitch\u002Fagents-best-practices.git \\\n  \"$HOME\u002F.claude\u002Fskills\u002Fagents-best-practices\"\n\n# Claude Code, project-level\nmkdir -p .claude\u002Fskills\ngit clone https:\u002F\u002Fgithub.com\u002FDenisSergeevitch\u002Fagents-best-practices.git \\\n  .claude\u002Fskills\u002Fagents-best-practices\n```\n\n\u003Cdiv align=\"center\">\n\n[Use cases](#use-cases) · [What this is](#what-this-is) · [Philosophy](#philosophy) · [Layout](#layout) · [Sources](#sources)\n\n\u003C\u002Fdiv>\n\n---\n\n## Use cases\n\nOnce installed, the skill activates when a conversation touches agent architecture, harness design, tool permissions, planning mode, context and memory, skills, connectors, observability, evals, prompt caching, or production readiness. Three common ways to use it:\n\n### Case 1 - Generate an MVP agent blueprint\n\nYou have a domain and need the smallest useful production-safe agent harness, not a vague list of best practices.\n\n```text\nYou    > Build an agent for account renewal risk. It should read CRM,\n         support tickets, and usage data, then draft renewal actions.\n\nAgent  > Start with an approval-gated Level 2 harness.\n         The MVP has one job: produce a renewal-risk brief plus draft\n         next actions for a human account owner.\n\n         Core loop:\n           user\u002Ftask -> context builder -> model call -> typed tool call\n           -> schema validation -> permission check -> execution or pause\n           -> structured observation -> next step or final brief\n\n         Minimal tools:\n           - read_account_profile      read_private_data\n           - list_support_tickets      read_private_data\n           - fetch_usage_summary       read_private_data\n           - draft_customer_email      draft_external_message\n           - request_approval          approval_gate\n\n         Launch gate:\n           20 historical accounts, trace review, no unapproved external\n           sends, and human acceptance on at least 80% of draft actions.\n```\n\nThe primary reference is [`references\u002Fmvp-agent-blueprint.md`](references\u002Fmvp-agent-blueprint.md).\n\n### Case 2 - Audit an existing agent harness\n\nYou already have a working agent, but it is brittle, expensive, too broad, or hard to debug.\n\n```text\nYou    > Our research agent sometimes runs tools forever and forgets why\n         it made a decision after context compaction. Audit the harness.\n\nAgent  > The failure points are runtime-level, not prompt-level:\n           - no hard step\u002Ftool\u002Ftime\u002Fcost budget\n           - compaction preserves prose but loses active approvals\n           - tool results are unbounded and mix trusted\u002Funtrusted data\n           - no event trace for model output -> tool call -> observation\n\n         Fix order:\n           1. Add loop budgets and termination reasons.\n           2. Store plan, approvals, todos, and artifacts outside the prompt.\n           3. Make compaction rehydrate active state, not chat history.\n           4. Add evals for injection, missing tool result, timeout, and\n              budget exhaustion.\n```\n\nStart with [`references\u002Fagentic-loop.md`](references\u002Fagentic-loop.md), [`references\u002Fcontext-memory-compaction.md`](references\u002Fcontext-memory-compaction.md), and [`references\u002Fsecurity-evals-observability.md`](references\u002Fsecurity-evals-observability.md).\n\n### Case 3 - Design tools, permissions, and connectors\n\nYou need an agent to work with real systems without turning every API into an unsafe broad tool.\n\n```text\nYou    > The ops agent needs Slack, Linear, Google Drive, and our internal\n         deploy API. How should tools and permissions work?\n\nAgent  > Split by risk class. Reads can be autonomous when scoped.\n         Drafts can be autonomous when labeled. External writes, deploys,\n         destructive actions, privileged access, and financial operations\n         require an approval record outside the model.\n\n         Do not expose generic send_message, write_database, or run_command.\n         Wrap each action as a narrow typed tool with structured results and\n         deterministic permission checks.\n```\n\nUse [`references\u002Ftools-and-permissions.md`](references\u002Ftools-and-permissions.md) and [`references\u002Fskills-and-connectors.md`](references\u002Fskills-and-connectors.md).\n\n### Other things the skill is good for\n\n- **\"How do I add planning mode without making the agent passive?\"** -> use [`references\u002Fplanning-and-goals.md`](references\u002Fplanning-and-goals.md).\n- **\"How should auto-compaction preserve active work?\"** -> use [`references\u002Fcontext-memory-compaction.md`](references\u002Fcontext-memory-compaction.md).\n- **\"How do I make prompt caching work in a long-running agent?\"** -> use [`references\u002Fprompt-caching-and-cost.md`](references\u002Fprompt-caching-and-cost.md).\n- **\"How do I support OpenAI, Anthropic, and OpenAI-compatible APIs?\"** -> use [`references\u002Fprovider-api-patterns.md`](references\u002Fprovider-api-patterns.md).\n- **\"What should I check before launch?\"** -> use [`references\u002Fchecklists.md`](references\u002Fchecklists.md).\n\n---\n\n> *\"Keep the loop simple and make the runtime rigorous.\"*\n\n## What this is\n\nA reference for people building agentic systems where the model is only one part of the runtime. It helps design a harness that includes:\n\n- a provider-neutral model-tool-observation loop,\n- narrow typed tools and structured tool results,\n- runtime permission checks outside the model,\n- planning mode and approval-gated execution,\n- goal-like loops with budgets, checkpoints, validation, and stop rules,\n- context, memory, retrieval, and auto-compaction,\n- skills, MCP, and external connector governance,\n- prompt-cache-aware context layout and cost telemetry,\n- observability, evals, launch gates, and incident response.\n\nThis is the control plane around an agent: **instructions -> context builder -> model call -> tool proposal -> validation -> permission decision -> execution or approval pause -> observation -> next step or final answer**.\n\n## What this is not\n\n- Not only for coding agents.\n- Not a multi-agent framework by default.\n- Not a replacement for runtime authorization, sandboxing, or audit logs.\n- Not a prompt-only safety strategy.\n- Not a reason to expose broad tools like `execute_anything`, `send_message`, or `write_database`.\n\nUse the single-agent MVP first. Add subagents, goal loops, connectors, and broader autonomy only after measured failures justify them.\n\n## Layout\n\n```text\nagents-best-practices\u002F\n├── README.md                                 # public-facing overview and install notes\n├── SKILL.md                                  # skill entry point and trigger rules\n├── icon.jpeg                                 # skill image used by the README\n└── references\u002F\n    ├── mvp-agent-blueprint.md                # domain-specific MVP harness blueprint\n    ├── architecture.md                       # component model and harness boundaries\n    ├── agentic-loop.md                       # loop invariants, retries, budgets, stopping\n    ├── tools-and-permissions.md              # typed tools, risk classes, approvals\n    ├── planning-and-goals.md                 # planning mode and long-running goals\n    ├── context-memory-compaction.md          # context, memory, retrieval, compaction\n    ├── prompt-caching-and-cost.md            # stable prefixes and cost-aware context\n    ├── skills-and-connectors.md              # Agent Skills, MCP, connectors, tool search\n    ├── system-prompts-instructions.md        # instruction hierarchy and templates\n    ├── provider-api-patterns.md              # OpenAI, Anthropic, compatible APIs\n    ├── security-evals-observability.md       # guardrails, tracing, evals, launch gates\n    ├── agent-legibility-feedback-loops.md    # source-of-truth artifacts and cleanup\n    ├── checklists.md                         # implementation and audit checklists\n    ├── coverage-audit.md                     # topic coverage verification\n    └── source-links.md                       # official references and further reading\n```\n\n## Philosophy\n\nThe central tension this skill resolves: **how can an agent do useful work in real systems without turning the model into an unaudited operator?** The answer is a small set of runtime rules:\n\n1. **The harness acts, not the model** - the model proposes; application code validates, authorizes, executes, and records.\n2. **Every tool call gets a result** - denial, timeout, malformed arguments, and aborts are observations too.\n3. **Risk changes the loop** - reads, drafts, writes, external communications, financial actions, destructive actions, and privileged actions need different permission paths.\n4. **Draft and commit are separate** - high-risk side effects require approval records outside the prompt.\n5. **Context is built, not dumped** - retrieve just enough, label trust boundaries, and preserve active state across compaction.\n6. **Long-running work needs budgets** - step, time, token, cost, and tool-call budgets are part of the product.\n7. **Skills and connectors are progressively disclosed** - expose names and descriptions first; load detailed workflows only when relevant.\n8. **Repeated failures become harness features** - validators, tools, docs, evals, or policies beat repeating prompt advice.\n\nRead [`SKILL.md`](SKILL.md) first. Use [`references\u002Fmvp-agent-blueprint.md`](references\u002Fmvp-agent-blueprint.md) when the user asks to make or build an agent.\n\n## About Agent Skills\n\nAgent Skills package reusable domain knowledge so compatible agents can discover, load, and apply a workflow only when it is relevant. This repository uses the portable `SKILL.md` entrypoint and works as a Codex skill, a Claude Code skill, or a skill for other Agent-Skill-aware runtimes.\n\n## Sources\n\n- Agent Skills specification: [agentskills.io\u002Fspecification](https:\u002F\u002Fagentskills.io\u002Fspecification)\n- OpenAI function calling, tools, agents, guardrails, sandboxing, Responses, and prompt caching docs are listed in [`references\u002Fsource-links.md`](references\u002Fsource-links.md).\n- Anthropic agent, context engineering, tool writing, long-running harness, MCP, and Agent Skills references are listed in [`references\u002Fsource-links.md`](references\u002Fsource-links.md).\n- MCP specification and governance references are listed in [`references\u002Fsource-links.md`](references\u002Fsource-links.md).\n\n## License\n\nMIT - see [`LICENSE`](LICENSE).\n\n## Credits\n\nAuthored as an Agent Skill for provider-neutral agent harness design. The recommendations synthesize common production harness patterns across OpenAI, Anthropic, OpenAI-compatible APIs, Agent Skills, MCP, and external connector workflows.\n","agents-best-practices 是一个平台中立的代理技能项目，旨在为Codex、Claude Code等AI代理设计生成最小可行产品蓝图，并审计、重构和解释代理框架。其核心功能包括提供标准化的设计模板，支持多种场景下的代理技能开发，如研究、支持、运营、销售、财务、数据分析等。该项目采用MIT许可证开放源代码，适用于需要构建高效且安全的自动化工作流或智能代理的企业和个人开发者。通过简单的安装步骤即可集成到现有项目中，帮助用户快速搭建起符合最佳实践的AI代理系统。","2026-06-11 03:53:39","CREATED_QUERY"]