agent-skills

Use when producing agent/LLM evals, synthetic simulation data, or self-improvement pipelines for prompts, code, skills, agents, harnesses, and workflows. Covers AgentEvals/AgentV, Agent Skills evals, ASSERT, GEPA, Trace, VISTA, Agent Lightning, SkillOpt, Simula-style data design, progressive disclosure, deterministic workspaces, and release evidence. USE FOR: eval creation, EVAL.yaml, AgentEvals, AgentV, evals.json, ASSERT, judge-traces, behavior taxonomy, judges, graders, rubrics, synthetic data, simulation data, Simula, QDC, source-grounded generation, prompt optimization, agent improvement, skill improvement, harness hardening, progressive disclosure, deterministic workflows, GEPA, Trace, VISTA, Agent Lightning, SkillOpt DO NOT USE FOR: ordinary unit/integration tests without AI quality criteria (use testing), refactoring without eval or trace feedback (use refactor), generic Agent Skills packaging without eval or improvement work (use agent-skills)

Use when working with AI agent protocols, standards, interoperability specifications, evaluation contracts, synthetic simulation data, improvement pipelines, and agent steering workflows. Covers MCP, A2A, ACP, Agent Skills, AGENTS.md, ADL, Improve, x402, AP2, MCP Apps, cagent, and learn. USE FOR: agent protocol selection, comparing MCP vs A2A vs ACP, understanding agent standards ecosystem, choosing payment protocols, choosing eval standards, choosing improvement techniques, choosing synthetic data simulation techniques, steering from user feedback DO NOT USE FOR: specific protocol, eval, or improvement implementation details (use the sub-skills: mcp, a2a, acp, improve, learn, x402, etc.)

Use when a user corrects, rejects, edits, or redirects an LLM/agent response and the correction should become a reusable reasoning strategy. Converts feedback into generalized learnings for ~/.agents/STEERING.md with linked RDF/Turtle evidence. USE FOR: user corrections, preference feedback, rejected agent behavior, reasoning strategy updates, steering file maintenance DO NOT USE FOR: storing task facts (use memory), ordinary skill authoring (use agent-skills), project instruction files unrelated to feedback (use agents-md)

Use when implementing the Agent-to-Agent (A2A) protocol for inter-agent communication, task delegation, and multi-agent collaboration. USE FOR: agent-to-agent communication, task delegation between agents, Agent Card publishing, multi-agent collaboration DO NOT USE FOR: tool integration (use mcp), agent payments (use ap2 or x402), agent definition (use adl)

Use when implementing the Agent Communication Protocol (ACP) for REST-based agent-to-agent communication, task delegation, and multimodal message exchange. USE FOR: ACP agent servers, ACP client integration, agent discovery via manifests, run lifecycle management, session-based stateful workflows, BeeAI agents DO NOT USE FOR: JSON-RPC agent communication (use a2a), tool integration for LLMs (use mcp), agent payments (use ap2 or x402), agent definition (use adl)

Use when defining AI agents declaratively with Agent Definition Language (ADL). Covers agent identity, LLM configuration, tools, permissions, RAG inputs, and governance metadata. USE FOR: declarative agent blueprints, agent identity and permissions, LLM configuration, governance metadata DO NOT USE FOR: agent runtime orchestration (use cagent), tool integration (use mcp), agent communication (use a2a)

Use when creating, packaging, or distributing Agent Skills. Covers the SKILL.md specification, frontmatter schema, naming conventions, marketplace publishing, and the skills-ref validator. USE FOR: creating SKILL.md files, packaging reusable agent capabilities, marketplace publishing, frontmatter schema validation DO NOT USE FOR: project-level agent guidance (use agents-md), agent runtime configuration (use adl or cagent)

Use when creating or updating AGENTS.md files to guide AI coding agents. Covers file structure, placement, content guidelines, and best practices for project-level agent instructions. USE FOR: project-specific agent instructions, build/test commands for agents, coding conventions, repository-level guidance DO NOT USE FOR: reusable cross-project skills (use agent-skills), agent runtime definition (use adl)

Use when implementing the Agent Payments Protocol (AP2) for secure, compliant AI-driven commerce. Covers intent mandates, cart mandates, payment flows, and merchant integration. USE FOR: agent-driven purchases, secure commerce mandates, user-authorized shopping flows, payment credential verification DO NOT USE FOR: API micropayments (use x402), agent communication (use a2a), tool integration (use mcp)

Use when building or running multi-agent systems with Docker cagent. Covers YAML agent configuration, MCP tool integration, sub-agents, Docker MCP Gateway, and the cagent CLI. USE FOR: multi-agent orchestration, YAML agent configuration, Docker MCP Gateway, running agent teams locally DO NOT USE FOR: declarative agent definitions without runtime (use adl), agent-to-agent protocol (use a2a), tool server development (use mcp)

Use when building MCP Apps that serve interactive UI from MCP servers. Covers the ui:// URI scheme, HTML rendering in sandboxed iframes, and bidirectional communication between UI and host. USE FOR: rich UI in agent conversations, interactive dashboards from MCP servers, sandboxed iframe rendering DO NOT USE FOR: basic tool responses without UI (use mcp), agent communication (use a2a), full web applications

Use when implementing or integrating with the Model Context Protocol (MCP) for AI tool servers, resources, prompts, and context management. USE FOR: building MCP tool servers, exposing resources to agents, prompt templates, connecting agents to external APIs DO NOT USE FOR: agent-to-agent communication (use a2a), interactive UI rendering (use mcp-apps), agent payments (use x402 or ap2)

Use when implementing the x402 protocol for HTTP-native micropayments. Covers server middleware, client payment flows, facilitator integration, and stablecoin payments for APIs and AI agents. USE FOR: API micropayments, monetizing endpoints, stablecoin HTTP payments, automated agent payments for API access DO NOT USE FOR: full commerce flows with cart/checkout (use ap2), agent communication (use a2a), tool integration (use mcp)

Use when authoring, structuring, or consuming design tokens in the W3C Design Tokens Community Group (DTCG) format. Covers token types, groups, aliases, composite tokens, and file conventions. USE FOR: W3C DTCG token files, token types (color, dimension, typography), token aliases and references, token groups, composite tokens, .tokens.json files DO NOT USE FOR: transforming tokens into platform code (use style-dictionary), Figma variable management (use figma), component styling (use the relevant framework skill)

Use when working with Figma as the design source for a design system — including Variables, Dev Mode, Code Connect, the REST API, and MCP-based design-to-code workflows. USE FOR: Figma Variables, Figma Dev Mode, Code Connect, Figma REST API, Tokens Studio plugin, Figma MCP server, design-to-code handoff DO NOT USE FOR: token file format details (use design-tokens), token build pipelines (use style-dictionary), component documentation (use storybook)

Use when writing cross-framework UI components with Mitosis (Builder.io). Write components once in a JSX subset, compile to React, Vue, Angular, Svelte, Solid, Qwik, and more. USE FOR: Mitosis component authoring, cross-framework component compilation, multi-framework design system components, Mitosis JSX syntax, mitosis.config.js DO NOT USE FOR: single-framework components (use the framework's own skill), design token management (use design-tokens or style-dictionary), component documentation (use storybook)

Use when building or maintaining a design system — the coordinated set of design tokens, component libraries, documentation, and tooling that ensures visual and behavioral consistency across products. USE FOR: design system architecture, choosing token formats vs component frameworks, connecting Figma to code, design-to-development workflows, multi-platform consistency DO NOT USE FOR: specific token authoring (use design-tokens), Figma workflows (use figma), component cataloging (use storybook), token transformation (use style-dictionary), cross-framework components (use mitosis)

Use when documenting, developing, or testing UI components with Storybook. Covers CSF3, CSF Factories, play functions, Args, interaction testing, and addon configuration. USE FOR: Storybook stories (CSF3 and CSF Factories), play functions, Args and ArgTypes, interaction testing, Storybook addons, visual regression testing, component documentation DO NOT USE FOR: design token authoring (use design-tokens), token transformation (use style-dictionary), Figma design handoff (use figma), cross-framework component compilation (use mitosis)

Use when transforming design tokens into platform-specific outputs using Style Dictionary. Covers configuration, transforms, formats, DTCG support, and multi-platform builds. USE FOR: Style Dictionary configuration, token transforms, platform-specific token output (CSS, SCSS, iOS, Android, Compose), custom formats, DTCG-to-platform pipelines DO NOT USE FOR: authoring token files (use design-tokens), Figma variable management (use figma), component documentation (use storybook)

Use when solving problems involving permutations, combinations, backtracking, branch and bound, subset generation, and constraint satisfaction. Covers N-Queens, Sudoku solving, generating functions, and pruning strategies. Based on Knuth's TAOCP Vol. 4A. USE FOR: permutation and combination generation, backtracking algorithm design, constraint satisfaction problems, branch and bound optimization, subset enumeration, pruning strategy selection DO NOT USE FOR: graph traversal (use graph-algorithms), optimization with overlapping subproblems (use dynamic-programming)

Use when selecting, implementing, or reasoning about data structures. Covers arrays, linked lists, stacks, queues, hash tables, trees (BST, AVL, Red-Black, B-Tree, Trie), heaps, and graphs (adjacency list, adjacency matrix). Based on Knuth's TAOCP Vol. 1. USE FOR: choosing data structures by access pattern, understanding operation complexities, implementing fundamental data structures, comparing data structure tradeoffs DO NOT USE FOR: graph algorithms on data structures (use graph-algorithms), sorting data (use sorting-searching)

Use when solving optimization problems with overlapping subproblems and optimal substructure. Covers memoization (top-down) vs tabulation (bottom-up), classic DP problems (Knapsack, LCS, LIS, Edit Distance, Coin Change, Matrix Chain, Rod Cutting), and the DP framework. Based on Knuth's TAOCP. USE FOR: optimization problems with overlapping subproblems, memoization strategies, tabulation approaches, recognizing DP problem patterns, state definition and recurrence formulation DO NOT USE FOR: graph shortest paths (use graph-algorithms), sorting (use sorting-searching)

Use when working with graph problems including traversal, shortest paths, minimum spanning trees, topological sorting, and connectivity analysis. Covers BFS, DFS, Dijkstra, Bellman-Ford, Floyd-Warshall, Prim, Kruskal, Tarjan, Kosaraju, A*, and Union-Find. Based on Knuth's TAOCP. USE FOR: graph traversal, shortest path computation, minimum spanning tree construction, topological sorting, strongly connected components, pathfinding, union-find operations DO NOT USE FOR: basic data structure operations (use data-structures), optimization problems (use dynamic-programming)

Use when selecting algorithms, analyzing complexity, or reasoning about data structure choices. Covers Big-O notation, space vs time tradeoffs, amortized analysis, and algorithmic problem-solving strategy based on Knuth's "The Art of Computer Programming." USE FOR: algorithm selection, Big-O analysis, complexity comparison, choosing data structures, algorithmic problem-solving strategy DO NOT USE FOR: specific algorithm implementations (use sub-skills), system architecture (use dev/architecture), design patterns (use dev/design-patterns)

Use when implementing or selecting sorting and searching algorithms. Covers comparison sorts (Quicksort, Mergesort, Heapsort, Insertion sort, Timsort), linear sorts (Counting, Radix, Bucket), and searching techniques (binary search, interpolation search, two pointers, sliding window). Based on Knuth's TAOCP Vol. 3. USE FOR: sorting algorithm selection, searching algorithm selection, understanding sort stability, complexity comparison of sorting methods, binary search variations, two-pointer and sliding window techniques DO NOT USE FOR: graph traversal (use graph-algorithms), dynamic programming (use dynamic-programming)

Domain-Driven Design (DDD) strategic and tactical patterns based on Eric Evans' "Domain-Driven Design" -- covering bounded contexts, aggregates, context maps, and ubiquitous language for modeling complex domains. USE FOR: bounded context identification, context mapping, aggregate design, ubiquitous language, domain modeling, subdomain classification, strategic domain design, tactical DDD patterns DO NOT USE FOR: event sourcing mechanics (use event-driven), microservice decomposition (use microservices), hexagonal ports/adapters (use hexagonal)

Event-Driven Architecture (EDA), Event Sourcing, and CQRS -- complementary but independent patterns for building reactive, scalable systems with rich audit trails and temporal queries. USE FOR: event-driven architecture, event sourcing, CQRS, event stores, projections, eventual consistency, compensating transactions, temporal queries DO NOT USE FOR: messaging channel patterns (use dev/integration-patterns), message routing (use dev/integration-patterns/message-routing), domain modeling (use domain-driven-design)

Hexagonal Architecture (Ports and Adapters), Onion Architecture, and their relationship to Clean Architecture -- enabling technology-independent domain logic with high testability. USE FOR: hexagonal architecture, ports and adapters, onion architecture, driving/driven adapters, technology-independent domain design, adapter-based testability DO NOT USE FOR: clean architecture layers specifically (use dev/craftsmanship/clean-architecture), microservice boundaries (use microservices), domain model design (use domain-driven-design)

Microservice architecture patterns and practices based on Sam Newman's "Building Microservices" -- covering service decomposition, inter-service communication, data management, and operational patterns. USE FOR: microservice decomposition, inter-service communication, service mesh, API gateway, saga pattern, service discovery, distributed data management DO NOT USE FOR: monolithic architecture (use monoliths), event sourcing details (use event-driven), domain modeling (use domain-driven-design)

Monolithic architecture patterns including modular monolith design, monolith-first strategy, and migration paths to microservices via the Strangler Fig pattern. USE FOR: monolith-first strategy, modular monolith design, monolith decomposition, Strangler Fig migration, avoiding Big Ball of Mud, when to keep a monolith DO NOT USE FOR: microservice decomposition (use microservices), event-driven architecture (use event-driven), clean architecture layers (use dev/craftsmanship/clean-architecture)

Use when selecting architecture styles, evaluating system decomposition strategies, or analyzing architecture characteristics (quality attributes) for a system. USE FOR: architecture style selection, comparing monolith vs microservices, architecture characteristics analysis, system decomposition strategy DO NOT USE FOR: specific style details (use sub-skills: microservices, monoliths, event-driven, etc.), code-level patterns (use dev/design-patterns), integration messaging (use dev/integration-patterns)

Cloud well-architected frameworks from AWS, Azure, and GCP -- covering pillars, design principles, review processes, and cross-cloud comparison for building reliable, secure, cost-effective cloud workloads. USE FOR: well-architected reviews, cloud architecture evaluation, reliability/security/cost/performance pillar analysis, cross-cloud architecture comparison DO NOT USE FOR: cloud infrastructure provisioning (use iac/terraform, iac/bicep, etc.), specific cloud services, microservice patterns (use microservices)

Use when designing APIs — REST endpoints, GraphQL schemas, gRPC services, or WebSocket protocols — including resource naming, versioning, pagination, error handling, and API gateway patterns. USE FOR: REST API design, GraphQL schema design, gRPC service definition, WebSocket protocol design, API versioning, pagination strategies, API gateway patterns, idempotency, OpenAPI specifications DO NOT USE FOR: data storage design (use data-modeling), authentication mechanisms (use authentication), API testing (use testing/api-testing)

Use when designing authentication and authorization systems — OAuth 2.0 flows, JWT handling, session management, RBAC/ABAC models, multi-tenancy patterns, and security header configuration. USE FOR: authentication design, authorization models, OAuth 2.0 flows, JWT implementation, session management, RBAC, ABAC, multi-tenancy patterns, identity provider selection, security headers, CORS configuration DO NOT USE FOR: API endpoint design (use api-design), security scanning/SAST (use testing/static-analysis), infrastructure security (use iac)

Use when designing caching strategies — choosing between cache-aside, read-through, write-through, write-behind, and write-around patterns, planning cache invalidation, and implementing multi-tier caching architectures. USE FOR: caching strategy selection, cache invalidation, cache-aside pattern, read-through/write-through/write-behind patterns, CDN caching, HTTP caching, Redis/Memcached architecture, multi-tier caching, cache stampede prevention DO NOT USE FOR: database design (use data-modeling), API endpoint design (use api-design), CDN infrastructure setup (use iac)

Use when designing database schemas, choosing data modeling strategies, or making decisions about data storage architecture across relational, document, graph, key-value, and time-series paradigms. USE FOR: database schema design, data modeling patterns, normalization/denormalization, document modeling, graph modeling, key-value design, time-series modeling, schema migration strategies, database-per-service decisions DO NOT USE FOR: ERD diagramming (use specs/diagramming/erd), API design (use api-design), caching strategy (use caching)

Use when making backend architecture decisions — choosing API styles, database types, caching strategies, authentication mechanisms, and server-side design patterns for scalable, maintainable systems. USE FOR: backend architecture decisions, choosing API styles, choosing database types, server-side design patterns, backend system design DO NOT USE FOR: specific pattern details (use sub-skills: data-modeling, api-design, caching, authentication), frontend architecture (use dev/frontend), infrastructure (use iac)

Use when designing system boundaries, dependency direction, and layered architecture — based on Robert C. Martin's "Clean Architecture." USE FOR: dependency rule enforcement, layer separation, boundary design, use case isolation, screaming architecture, presenter/viewmodel patterns DO NOT USE FOR: code-level clean practices (use clean-code), hexagonal/ports-adapters specifically (use dev/architecture/hexagonal), microservices (use dev/architecture/microservices)

Use when writing or reviewing code for readability, maintainability, and expressiveness — based on Robert C. Martin's "Clean Code." USE FOR: naming conventions, function design, comment quality, formatting standards, error handling strategy, code readability improvements DO NOT USE FOR: architecture layers (use clean-architecture), refactoring techniques (use refactoring), SOLID principles (use solid)

Use when identifying code smells and applying systematic refactoring techniques — based on Martin Fowler's "Refactoring." USE FOR: code smell identification, refactoring technique selection, safe code transformation, incremental improvement workflows, legacy code improvement DO NOT USE FOR: clean code principles (use clean-code), design pattern application (use dev/design-patterns), architecture restructuring (use dev/architecture)