Personal Productivity
YouTube ... Quora ...Google search ...Google News ...Bing News
- Agents/Assistants ... Robotic Process Automation ... Personal Companions ... Productivity ... Email ... Negotiation ... LangChain - Immersive Reality ... Metaverse ... Omniverse ... Transhumanism ... Religion - Simulation ... Simulated Environment Learning ... World Models ... Minecraft: Voyager - Case Studies
- Development ... Notebooks ... AI Pair Programming ... Codeless ... Hugging Face ... AIOps/MLOps ... AIaaS/MLaaS - 16 AI Tools to Speed Up Your Work | Prathamesh Ingle - MarketTechPost - The best AI productivity tools in 2023 | Miguel Rebelo - Zapier ... These 36 AI apps will help you work faster—and better.
AI can significantly enhance personal productivity by automating tasks, providing intelligent insights, and streamlining decision-making processes. Here are some ways AI provides personal productivity benefits:
- Task Automation: AI can automate repetitive and time-consuming tasks, freeing up valuable time for users to focus on more important and creative activities. For instance, AI-powered virtual assistants can schedule meetings, manage emails, set reminders, and perform other administrative tasks, reducing the burden on the user.
- Smart Scheduling: AI can analyze your calendar, preferences, and other relevant data to suggest the most optimal times for meetings and appointments. This minimizes scheduling conflicts and ensures you can allocate your time effectively.
- Personalized Recommendations: AI algorithms can analyze your habits, preferences, and past behavior to offer personalized recommendations. For example, in email applications, AI can prioritize important emails or categorize messages based on their relevance, saving you time sorting through your inbox.
- Knowledge Management: AI-powered tools can help you organize and access information more effectively. From intelligent note-taking apps that categorize and search your notes to content curation tools that deliver relevant articles based on your interests, AI enhances knowledge management.
- Workflow Optimization: AI can optimize workflows by identifying bottlenecks, suggesting process improvements, and automating repetitive steps. This streamlines operations and improves overall efficiency.
- Personalized Learning: AI-driven educational platforms can adapt to your learning pace, identify your strengths and weaknesses, and provide personalized learning paths, helping you acquire new skills efficiently.
- Document and Information Management: AI can assist in document management by categorizing files, extracting relevant information, and even summarizing lengthy texts, making it easier to access and process information.
Personal Agent
A Personal Agent library is a collection of reusable AI prompts organized around a small team of specialists. Instead of writing a new prompt from scratch every time you need help, you call on a specialist you have already defined and tell it which job to do. This page explains how to structure the library, describes each specialist and the jobs it performs, and offers guidelines for growing the library over time.
Roles & Actions
The Core Idea
A useful way to organize reusable AI prompts is to separate two things that people often blend together: - The Agent (specialist) role defines who does the work. - The Action defines what work gets done.
The Agent defines a stable professional identity. It captures the specialist's expertise, reasoning style, quality standards, and general area of responsibility. These qualities rarely change.
The Action defines the specific task the agent performs right now. Actions are narrower, more concrete, and more numerous than agents.
This separation creates a cleaner and more reusable hierarchy than treating every individual prompt as its own separate agent.
An Analogy: Hiring a Professional
Imagine you hire an accountant. You explain your expectations once: be accurate, cite the relevant rules, and flag anything that looks risky. After that, you can ask the same accountant to prepare your taxes, reconcile your accounts, or review the payment terms in a contract. You do not hire and onboard a brand-new accountant for each job.
Prompts work the same way. The agent is the professional you hired. The actions are the jobs you hand them.
The Problem This Solves
Without this separation, prompt libraries tend to sprawl. Each task gets its own standalone prompt, and each prompt restates the same identity, expertise, and rules. Over time, this causes three problems: - Duplication: The same instructions appear in dozens of places. - Drift: When you improve one prompt, the others fall out of sync. - Confusion: Similar prompts overlap, and you can no longer tell which one to use.
Separating agents from actions fixes all three. You define each specialist once, and every action inherits that definition.
Prompt Structure
A practical structure has four layers:
Agent (specialist) - Role (responsibility)
→ Actions
→ Task-specific input
→ Output requirements
Each layer answers a different question and changes at a different rate:
| Layer | Question it answers | How often it changes | Example |
|---|---|---|---|
| Agent (specialist) | Who does this work, and how do they think? | Rarely | Technical Editor |
| Role (responsibility) | What does this specialist own? | Rarely | Updates and improves structured technical content |
| Action | Which specific task should the agent perform? | Occasionally, when you add new actions | Expand Content |
| Task-specific input | What material does the agent work on this time? | Every request | Rough notes about a new feature |
| Output requirements | What should the result look like? | Often | Use headings and bullet points; avoid em dashes |
Worked Example
Consider this request:
Act as a Technical Editor. Take the provided brief notes or outline and expand them into comprehensive, clear documentation. Add necessary context, examples, and analogies. Use professional, conversational English and prioritize active voice. Organize the text with clear headings and bullet points. Do not use em dashes.
Here is how that request breaks down into layers: - Agent: Technical Editor - Role: Updates and improves structured technical content - Action: Expand Content - Task-specific input: The brief notes or outline - Output requirements: Professional, conversational English; active voice; clear headings and bullet points; no em dashes
The same Technical Editor could handle a completely different job, such as Reorganize Content, if you simply swap the action. The identity and standards stay the same.
Deciding What Goes Where
Use this rule of thumb when you write a new instruction: - Put it in the agent definition if it should apply to every task that agent performs. - Put it in the action definition if it applies only to that type of task. - Put it in the output requirements if it applies only to this one request.
An example agent definition:
You are a Technical Editor. You improve structured technical content so that it is accurate, clear, and easy to navigate. You preserve the author's intent, keep terminology consistent, and flag any claim you cannot verify.
An example action definition:
Action: Expand Content. Turn the provided notes or outline into complete documentation. Add context, examples, and analogies wherever a point would otherwise be hard to follow. Do not invent facts the notes do not support.
Agent Catalog
The table below lists every agent in the library, what it owns, the actions it performs, and the situations that call for it.
| Agent (specialist) | Role (responsibility) | Actions | Call on it when... |
|---|---|---|---|
| Research Analyst | Investigates, evaluates, compares, verifies, and identifies gaps | Currentness Audit; Relevance Audit; Gap Analysis; Strategic Analysis; Red-Team Analysis | You need to know whether something is accurate, current, complete, or sound |
| Solution Architect | Turns identified problems or gaps into a structured solution | Develop Solution; Explore Alternatives; Requirements Clarification; Recommend Approach | You understand the problem and need a plan to solve it |
| Knowledge Synthesizer | Combines source material without losing important information | Merge Sources; Consolidate Documents; Reconcile Conflicts; Retention Audit | You have several sources and need one coherent result |
| Technical Editor | Updates and improves structured technical content | Update Page; Update Section; Expand Content; Reorganize Content | Existing content needs improving, updating, or expanding |
| Software Engineer | Implements and modifies software | Implement Feature; Fix Bug; Refactor; Update Bookmarklet | You need code written, fixed, or restructured |
| Systems Auditor | Tries to break specifications or systems and harden them | Adversarial Test; Regression Audit; Specification Gap Analysis; Consolidate Specification | You want to find weaknesses before real users do |
| Continuity Strategist | Preserves project state and transfers work between sessions or agents | Create Handoff; Capture Decisions; Identify Open Questions; Define Next Move | You are pausing work, starting a new session, or passing work to another agent |
| Workflow Orchestrator | Manager / Supervisor (agent placeholder) | Selects and sequences the agents and actions | A request is complex enough to need more than one agent or action |
Agent and Action Hierarchy
The distinction between agents and actions makes the prompt library easier to maintain and expand. The tree below shows the catalog as a quick visual map. Each agent sits at the top of its branch, and its actions hang beneath it.
Workflow Orchestrator (selects and sequences the agents below) Research Analyst ├── Currentness Audit ├── Relevance Audit ├── Gap Analysis ├── Strategic Analysis └── Red-Team Analysis Solution Architect ├── Develop Solution ├── Explore Alternatives ├── Requirements Clarification └── Recommend Approach Knowledge Synthesizer ├── Merge Sources ├── Consolidate Documents ├── Reconcile Conflicts └── Retention Audit Technical Editor ├── Update Page ├── Update Section ├── Expand Content └── Reorganize Content Software Engineer ├── Implement Feature ├── Fix Bug ├── Refactor └── Update Bookmarklet Systems Auditor ├── Adversarial Test ├── Regression Audit ├── Specification Gap Analysis └── Consolidate Specification Continuity Strategist ├── Create Handoff ├── Capture Decisions ├── Identify Open Questions └── Define Next Move
Agent Profiles
This section describes each agent in more detail and explains what every action does.
Research Analyst
The Research Analyst investigates before anyone acts. It evaluates claims, compares options, verifies facts, and finds what is missing. Think of it as a fact-checker and a strategist rolled into one. - Currentness Audit: Checks whether information is still up to date. It flags outdated versions, deprecated tools, broken links, and stale statistics. - Relevance Audit: Checks whether content still serves its intended audience and purpose. It identifies sections that have drifted off-topic or no longer matter. - Gap Analysis: Compares what exists against what should exist, then lists the missing topics, steps, or evidence. - Strategic Analysis: Evaluates options against your goals and weighs their tradeoffs, risks, and opportunities. - Red-Team Analysis: Argues against a plan, claim, or strategy on purpose to expose weak assumptions and blind spots.
Solution Architect
Once the problem is clear, the Solution Architect designs the fix. Like a building architect, it produces the blueprint but does not lay the bricks. Implementation belongs to other agents, such as the Software Engineer or the Technical Editor. - Develop Solution: Produces a complete, structured solution that covers components, steps, dependencies, and risks. - Explore Alternatives: Generates several genuinely different approaches and explains the tradeoffs of each. - Requirements Clarification: Surfaces ambiguities, asks the questions that need answers first, and states its assumptions before designing anything. - Recommend Approach: Chooses one option and explains why it beats the others.
Tip: These actions often run best in a natural sequence: clarify requirements, explore alternatives, recommend an approach, then develop the solution.
Knowledge Synthesizer
The Knowledge Synthesizer combines source material into a single, coherent result. Its defining standard is fidelity: the output should be more organized than the inputs, but it must never quietly drop anything important. Picture three people taking notes in the same meeting. The Knowledge Synthesizer turns their three versions into one official record that captures everything each person caught. - Merge Sources: Combines several different inputs into one coherent document. - Consolidate Documents: Collapses overlapping or redundant documents into a single source of truth. - Reconcile Conflicts: Identifies where sources disagree, then resolves each conflict or flags it for your decision. - Retention Audit: Compares the finished output against the original sources to confirm that nothing important went missing. Run this after every merge or consolidation.
Technical Editor
The Technical Editor updates and improves structured technical content such as wiki pages, guides, and specifications. It improves accuracy, clarity, and structure while keeping the original meaning intact. - Update Page: Revises an entire page for accuracy, clarity, and current information. - Update Section: Revises one section and leaves the rest of the page untouched. Use this action when you want to limit the scope of changes. - Expand Content: Turns brief notes or outlines into complete documentation with context, examples, and analogies. This page is itself a product of the Expand Content action. - Reorganize Content: Restructures headings, order, and flow without changing the underlying meaning.
Software Engineer
The Software Engineer implements and modifies software. It writes working code, explains its changes, and respects the existing conventions of the codebase. - Implement Feature: Builds new functionality from a specification or description. - Fix Bug: Diagnoses a defect, corrects it, and explains the root cause so the same bug does not return. - Refactor: Improves the internal structure and readability of code without changing what it does. Think of it as reorganizing a closet: everything is still there, but now you can find it. - Update Bookmarklet: Modifies a bookmarklet, which is a small piece of JavaScript saved as a browser bookmark that runs on the current page when you click it. This action shows that the library can hold narrow, personal actions alongside general ones.
Systems Auditor
The Systems Auditor tries to break specifications and systems so you can harden them. It works like a crash-test engineer who wrecks cars on purpose so that real drivers stay safe. - Adversarial Test: Deliberately feeds the system edge cases, malformed inputs, and misuse scenarios to see what breaks. - Regression Audit: Checks that recent changes have not broken behavior that used to work. - Specification Gap Analysis: Finds what a specification fails to define, such as unhandled errors, undefined edge cases, or rules that contradict each other. - Consolidate Specification: Folds the fixes and clarifications from testing back into a single, hardened specification.
Red-Team Analysis vs. Adversarial Test: Both actions involve deliberate opposition, but they target different things. The Research Analyst red-teams ideas, arguments, and strategies. The Systems Auditor adversarially tests concrete systems and specifications.
Continuity Strategist
The Continuity Strategist preserves project state and transfers work between sessions or agents. This matters because AI chat sessions have limited context and usually do not remember earlier conversations. Without deliberate handoffs, decisions get lost and work gets repeated.
Think of a hospital shift change. The outgoing nurse tells the incoming nurse what happened, what the team decided, what to watch for, and what to do next. The Continuity Strategist writes that report for your projects. - Create Handoff: Produces a self-contained summary that lets a new session or a different agent pick up exactly where the work left off. - Capture Decisions: Records what you decided and why, so nobody reopens settled questions. - Identify Open Questions: Lists the unresolved issues that still need answers. - Define Next Move: Names the single most useful next step.
Workflow Orchestrator (Placeholder)
The Workflow Orchestrator acts as a manager or supervisor. It does not perform the work itself. Instead, it decides who does what and in which order, much like a conductor who never plays an instrument but directs the whole orchestra.
The orchestrator answers four questions:
- What kind of request is this?
- Which agent should handle it?
- Which actions are required?
- In what sequence should they run?
This agent is currently a placeholder. For now, you fill this role yourself each time you choose an agent and an action. Later, you can turn it into its own prompt that routes requests automatically.
Example workflow. Suppose the request is: "Our onboarding documentation is out of date and spread across three separate pages." The orchestrator might sequence the work like this:
- Research Analyst → Currentness Audit: Identify outdated information on each of the three pages.
- Knowledge Synthesizer → Merge Sources: Combine the three pages into one document.
- Knowledge Synthesizer → Retention Audit: Confirm that the merge kept everything important.
- Technical Editor → Update Page: Apply the corrections that the audit identified.
- Continuity Strategist → Create Handoff: Summarize what changed and list any open questions.
The output of each step becomes the task-specific input for the next step.
Benefits of This Approach
This approach allows a relatively small library of well-defined agents to support many specialized tasks without duplicating role definitions, reasoning instructions, or operating principles across dozens of individual prompts.
Consider the numbers. The catalog above defines 7 working agents and 29 actions. Without the agent and action split, you would maintain 29 standalone prompts, and each one would restate its specialist's identity and standards. With the split, you maintain 7 agent definitions plus 29 short action definitions that reuse them.
Key benefits include: - Less duplication: You define each specialist's expertise and standards once. - Consistency: Every action performed by the same agent follows the same standards. - Easier maintenance: You update an agent once, and all of its actions inherit the change. For example, if you want every Technical Editor task to follow a house style guide, you add that rule to the agent definition and all four actions pick it up immediately. - Easier growth: You can add a new action in a few lines without creating a new agent. - Clearer choices: Each agent has a distinct responsibility, so you can quickly tell which one fits a request. - Composable workflows: You can chain actions from different agents to handle complex, multi-step work.
Guidelines for Growing the Library
- Add an action before you add an agent. If a new task fits an existing agent's responsibility, make it a new action under that agent. - Create a new agent only for distinct expertise. Ask yourself: "Would this professional plausibly be asked to do this job?" If the answer is yes, you need an action, not an agent. - Name actions clearly. Use short task names that describe the work, such as Fix Bug, Merge Sources, or Gap Analysis. - Keep agent definitions stable. Put task-specific instructions in the action and one-time instructions in the output requirements. - Document overlaps. When two actions from different agents look similar, write down the difference, as this page does for Red-Team Analysis and Adversarial Test. - Pair creation with verification. Follow actions that produce something with actions that check it. For example, pair Merge Sources with Retention Audit, and pair Implement Feature with Regression Audit.
Agent Environment
Claude Agent Environment
From Prompt Library to Agent Environment
The Agent and Action catalog above is a prompt library: you choose a specialist, paste its definition, and hand it a task. An agent environment such as Claude Code keeps the same design but adds the runtime that a prompt cannot provide: - Tools that let each agent act instead of only advising. - Separate context windows so each specialist works without cluttering the main conversation. - Persistent state that survives between sessions. - Automatic routing based on each agent's description.
Because the library already separates agents from actions, moving to an agent environment is mostly a translation job, not a redesign.
How the Pieces Map
| Catalog element | Agent environment (Claude Code) | What you gain |
|---|---|---|
| Agent definition | Subagent file in .claude/agents/
|
Own context window, tool permissions, and model |
| "Call on it when..." column | The description field
|
Claude routes work automatically |
| Action | Skill folder with a SKILL.md file
|
Runs as /expand-content or triggers automatically
|
| Agent and Action pairing | Skill with context: fork and agent: technical-editor
|
The action runs inside the specialist |
| Recurring output requirements | CLAUDE.md
|
Applies to every agent |
| One-time output requirements | Your message | Unchanged |
| Workflow Orchestrator | The main conversation, plus one workflow skill per pipeline | No longer a placeholder |
| Continuity Strategist output | Files in the project, plus subagent memory | Survives across sessions |
| The whole library | A plugin | Installs in any project |
A subagent is a Markdown file with YAML frontmatter. The frontmatter configures the agent (name, description, tools, model), and the body becomes its system prompt. That body is your existing agent definition. Skills are the actions. Adding context: fork to a skill's frontmatter runs the skill in an isolated subagent, and the agent field names which subagent handles it. The reverse also works: a subagent's skills field preloads the full content of named skills at startup, so a Technical Editor could start with all four of its actions already loaded.
What Actually Changes
Agents Get Tools
Today the Research Analyst describes what a Currentness Audit would check. In an agent environment, it fetches the links, checks the versions, and reports what it found. The Systems Auditor stops imagining malformed inputs and actually runs them. This also makes the distinction between Red-Team Analysis and Adversarial Test concrete: one is read-only reasoning, and the other gets a shell.
The Test for a New Agent Changes
In the prompt library, a new agent means distinct expertise. In an agent environment, a subagent earns its place when the work needs isolated context, restricted tools, or a different model. Expertise alone can live in a skill.
This rule has two consequences that are easy to miss: - Subagents start fresh. A subagent does not see your conversation history. Create Handoff therefore cannot run as a standard subagent, because it would have nothing to summarize. The Continuity Strategist's actions must run in the main conversation. - Subagents cannot ask you questions. Claude Code withholds the question tool from subagents. Requirements Clarification, whose whole job is asking questions, must also run in the main conversation.
Isolation helps elsewhere. The Systems Auditor benefits from a fresh context, because a reviewer that never saw the author's reasoning makes a better adversary.
Handoffs Become Files
The orchestrator example states that the output of each step becomes the input for the next step. Subagents return only a summary to the main conversation, so each step should write its full result to disk, such as an audit report or a merged draft. Retention Audit can then compare actual files instead of relying on memory.
Descriptions Do the Routing
Claude reads each agent's and skill's description to decide when to use it. The "Call on it when..." column in the Agent Catalog therefore becomes the most important text in the migration. A vague description leads to misrouted work.
Which Agents Become Subagents
| Agent | Implementation | Reason |
|---|---|---|
| Research Analyst | Subagent | Needs web tools, produces verbose output, and works read-only |
| Systems Auditor | Subagent | Benefits from fresh eyes; needs read-only access plus a shell to run tests |
| Software Engineer | Subagent | Needs edit and shell access; can work in an isolated copy of the repository |
| Knowledge Synthesizer | Subagent | Reads large amounts of source material that would crowd the main conversation |
| Technical Editor | Start inline; promote if needed | Works either way; promote it if the main conversation gets cluttered |
| Solution Architect | Mixed | Requirements Clarification stays inline; the other actions can fork |
| Continuity Strategist | Inline skills | Needs the full conversation history |
| Workflow Orchestrator | Main conversation | Selects and sequences the other agents |
Migration Path
Step 1: Turn the Wiki into Source Files
Split each agent and each action into its own file. Rewrite every "Call on it when..." entry as a description that says when to use the agent or action, not only what it does. Then make this wiki page document those files instead of duplicating them. Otherwise, the library recreates the drift problem described in The Problem This Solves.
Step 2: Test in Claude.ai (Optional)
Claude.ai accepts uploaded skills, so you can test the library without a terminal. Package each agent as one skill:
- SKILL.md holds the agent definition and an index of its actions.
- Each action lives in a separate reference file that loads only when needed.
This step tests routing cheaply, but it does not provide isolation or per-agent tools.
Step 3: Move Two Agents into Claude Code
Start with the Technical Editor and the Systems Auditor, because together they exercise both patterns (inline and forked). The project layout looks like this:
CLAUDE.md ← house style: active voice, no em dashes
.claude/
agents/
technical-editor.md
systems-auditor.md
skills/
expand-content/SKILL.md
adversarial-test/SKILL.md
create-handoff/SKILL.md ← inline, no fork
docs/
HANDOFF.md
DECISIONS.md
work/ ← artifacts passed between steps
The agent file contains your existing definition plus configuration:
--- name: technical-editor description: Updates, expands, and reorganizes wiki pages, guides, and specs. Use when existing documentation needs improving. tools: Read, Edit, Write, Grep, Glob, WebFetch model: sonnet --- You improve structured technical content so that it is accurate, clear, and easy to navigate. Preserve the author's intent, keep terminology consistent, and flag any claim you cannot verify.
Each action binds itself to its agent:
--- name: expand-content description: Turn brief notes or an outline into complete documentation. context: fork agent: technical-editor --- Turn the provided notes into complete documentation. Add context, examples, and analogies where a point would be hard to follow. Do not invent facts. Write the result to docs/work/ and return a short summary of what you added.
House style goes in CLAUDE.md. Custom subagents load the same CLAUDE.md files as the main conversation, so a rule added there reaches every agent. This extends the benefit described in Benefits of This Approach: you update one file, and every agent and action inherits the change.
Step 4: Give Agents Tools and State
- Connect the wiki. Connect the wiki's API, directly or through an MCP server, so the Technical Editor reads and writes pages instead of receiving pasted text. You can scope a connection to a single subagent so its tools stay out of the main conversation.
- Enable memory. For agents that should learn over time, the memory field gives the subagent a persistent directory that survives across sessions.
- Bundle scripts. A skill can include script files alongside its instructions, which suits narrow actions such as Update Bookmarklet.
Step 5: Promote the Orchestrator, Then Package
Write each recurring workflow as its own skill. For example, a /refresh-docs skill can sequence the five steps from the onboarding example and build in the guideline to pair creation with verification. Once several workflows are stable, bundle the agents and skills into a plugin so the whole library installs in any project.
Claude See Also
- Create custom subagents (Claude Code documentation) - Skills (Claude Code documentation) - Plugins (Claude Code documentation) - MCP servers (Claude Code documentation) - CLAUDE.md and memory (Claude Code documentation)
OpenAI Agent Environment
From Prompt Library to OpenAI Agent Environment
The same Agent and Action catalog maps cleanly to OpenAI's current agent stack. The closest managed equivalent to Claude Code is the OpenAI Agents API, which runs the Codex harness for you and can provide durable sessions, multi-agent orchestration, skills, tools, sandboxed files, and published artifacts. The OpenAI Agents SDK is the code-first alternative when you want your own Python or TypeScript application to own the agent loop, tools, approvals, state, and specialist definitions.
For this library, the practical target is:
- Agents API for a managed, durable agent environment with an OpenAI-hosted or self-hosted sandbox.
- Agents SDK when you want explicit Agent(...) definitions, manager/specialist ownership, typed function tools, guardrails, approvals, and application-controlled orchestration.
- Responses API only when you need lower-level control and are prepared to assemble more of the agent runtime yourself.
The important point is that the catalog does not need a conceptual redesign. It needs one additional distinction:
Agent = WHO owns the work Skill = HOW a repeatable kind of work is performed Tool = WHAT executable capability the agent can use
An artifact is then the durable result of that work, while a session and sandbox preserve the working state around it.
Do not build this migration around Agent Builder. OpenAI announced that Agent Builder is being wound down, with the product scheduled to become unavailable after November 30, 2026. For a durable implementation, use the Agents API or Agents SDK.
How the Pieces Map
| Catalog element | OpenAI implementation | What you gain |
|---|---|---|
| Agent definition | Agent(...) with instructions in the Agents SDK, or the root agent configuration in an Agents API session
|
Stable specialist identity, model choice, tools, guardrails, and ownership |
| Role (responsibility) | Agent instructions
|
The specialist's durable contract |
| "Call on it when..." column | handoffDescription, an agent-as-tool description, or skill description
|
Better routing and delegation |
| Action | Skill directory containing SKILL.md
|
Reusable workflow instructions, references, examples, and scripts |
| Agent and Action pairing | Agent instructions plus the skills exposed in that agent's sandbox or capability directories | A specialist can reuse several actions without duplicating its identity |
| Task-specific input | User input plus files placed or mounted in the sandbox | Large inputs do not have to be pasted into the prompt |
| Recurring workspace requirements | AGENTS.md
|
Shared repository or workspace conventions |
| Specialist-specific requirements | Agent.instructions
|
Rules that apply only to that specialist |
| One-time output requirements | The current user message | Remains task-specific |
| Executable business action | Function tool, hosted tool, MCP tool, shell, or other runtime tool | The agent can act instead of merely describing what to do |
| Workflow Orchestrator | Root manager agent | Selects, sequences, delegates, and synthesizes |
| Specialist delegation | agent.as_tool(...) or handoffs=[...] in the Agents SDK; managed subagents in the Agents API
|
Explicit control over who owns the final response |
| Continuity Strategist output | Session state, workspace files, snapshots, and explicit handoff/decision artifacts | Work can continue across turns or later runs |
| Finished document, spreadsheet, report, code file, etc. | Artifact written to /workspace/outputs in an OpenAI-hosted Agents API sandbox
|
The finished file is published and remains retrievable after the sandbox itself expires |
| The reusable capability library | Plugin containing skills and MCP configuration | Portable installation of reusable workflows and integrations |
OpenAI's current skill format is intentionally close to the structure this catalog already needs. A skill is a directory with a SKILL.md manifest plus any supporting references, assets, examples, or scripts. In an Agents API sandbox, the harness discovers skills from registered capability directories. In the OpenAI migration convention, reusable skills commonly live under .agents/skills/.
The Most Important Change: Add Tools as a Separate Layer
The existing catalog separates Agents from Actions. OpenAI makes it useful to add a third layer: Tools.
Consider the Research Analyst's Currentness Audit: - Agent: Research Analyst - Skill: Currentness Audit - Tools: web search, file search, browser/MCP access, or a wiki API - Artifact: currentness report
The skill should explain the procedure: inspect dates, versions, links, deprecations, and unsupported claims. The tools perform the actual searches and retrieval.
The same pattern applies to the Software Engineer: - Agent: Software Engineer - Skill: Fix Bug - Tools: shell, file read/write, patching, tests, repository access - Artifact: modified code plus test results
This distinction prevents the Action catalog from turning into a collection of low-level tool definitions. Actions remain human-readable jobs. Tools remain machine-executable capabilities.
Skills Are Not Subagents
A skill and a specialist agent solve different problems.
- Create a skill when the important thing is a repeatable procedure, checklist, standard, template, or script. - Create a separate agent when the specialist needs different instructions, tools, guardrails, model settings, approval rules, context ownership, or response ownership. - Give one agent many skills when the same professional can perform several related jobs.
This reinforces the rule already established in Guidelines for Growing the Library: add an action before adding an agent. In OpenAI, that normally means adding a skill before adding another runtime agent.
How the Workflow Orchestrator Changes
The Workflow Orchestrator no longer needs to remain a placeholder. It becomes the root manager.
The OpenAI Agents SDK supports two canonical delegation patterns:
- Agent as a tool. The manager calls a specialist, receives its result, and remains responsible for the final answer. Use this when several specialists contribute to one combined result.
- Handoff. The manager transfers ownership to a specialist, which then owns the next response. Use this when the specialist should take over the conversation.
For this catalog, agent as a tool should be the default pattern. The Workflow Orchestrator was explicitly designed to select agents, sequence their actions, and combine the result. Handoffs are better reserved for cases where you deliberately want a specialist to own the conversation from that point forward.
The managed Agents API offers another pattern: enable multi-agent orchestration and allow the root agent to create independent subagents. Each subagent gets its own context and can work in parallel. This is especially useful for independent research, document review, testing, or several audits that can run at the same time.
Which Catalog Members Should Become Runtime Agents
Not every catalog specialist needs to become a separate runtime agent on day one.
| Catalog member | Recommended OpenAI implementation | Reason |
|---|---|---|
| Workflow Orchestrator | Root manager agent | Owns routing, sequencing, synthesis, and final response |
| Research Analyst | Specialist agent, normally called as a tool | Benefits from read-only web/file tools and an isolated research context |
| Systems Auditor | Specialist agent, normally called as a tool | Benefits from fresh context, sandbox execution, and adversarial testing |
| Software Engineer | Specialist agent; tool-call or handoff depending on ownership | Needs a distinct edit/test tool surface and may own a long implementation branch |
| Knowledge Synthesizer | Start as a specialist agent for large source sets; otherwise a skill | Isolation helps when many documents would crowd the manager's context |
| Technical Editor | Start as skills on the manager; promote to an agent if needed | Most editing actions share tools and do not require separate ownership |
| Solution Architect | Start as skills; promote for long or tool-specific architecture work | Its actions are mostly reasoning procedures until implementation tools differ |
| Continuity Strategist | Mostly skills plus session/artifact conventions | OpenAI sessions and workspace state already provide much of the continuity layer |
This is a runtime decision, not a change to the conceptual catalog. The wiki can still document all seven specialists. The implementation simply avoids paying the complexity cost of seven independent agents before isolation is useful.
Artifacts, Working Files, and State
OpenAI separates three things that are easy to blur together:
- Working files live in the sandbox while the agent is doing the job. - Artifacts are finished files you deliberately publish or retrieve. - Session state preserves the conversation and agent progress.
With an OpenAI-hosted Agents API sandbox, each session has its own workspace. Files written under /workspace/outputs are published as immutable artifacts when the turn completes. Those published copies remain retrievable after the sandbox expires.
A clean convention for this catalog is:
/workspace/
inputs/ ← source material supplied to the task
work/ ← intermediate reports and drafts
outputs/ ← final published artifacts
state/
DECISIONS.md
HANDOFF.md
OPEN_QUESTIONS.md
The Continuity Strategist therefore still matters, but its role changes. Instead of compensating for a completely stateless chat, it maintains human-readable project state on top of the runtime's session state.
Guardrails, Approvals, and Tracing
An agent environment should define not only what an agent can do, but what it is allowed to do automatically.
OpenAI separates these concerns: - Tool exposure: which tools the agent can see. - Guardrails: checks on inputs, outputs, or tool use. - Approvals: pauses before actions that have side effects or require human review. - Tracing: records model calls, tool calls, handoffs, guardrails, and other steps for debugging and evaluation.
For example, the Software Engineer can be allowed to read and test freely while requiring approval before publishing, deploying, deleting, or writing to a production system. The Research Analyst can remain read-only.
This is a useful addition to the catalog because two agents may have identical skills but very different permission boundaries.
Recommended Source Layout
The source of truth should move out of the wiki and into version-controlled files. The wiki should document the catalog; the files should run it.
A practical starting layout is:
agent-catalog/
AGENTS.md ← shared workspace rules
agents/
workflow-orchestrator.md ← source text loaded into Agent.instructions
research-analyst.md
solution-architect.md
knowledge-synthesizer.md
technical-editor.md
software-engineer.md
systems-auditor.md
continuity-strategist.md
.agents/
skills/
currentness-audit/
SKILL.md
relevance-audit/
SKILL.md
gap-analysis/
SKILL.md
strategic-analysis/
SKILL.md
red-team-analysis/
SKILL.md
develop-solution/
SKILL.md
explore-alternatives/
SKILL.md
requirements-clarification/
SKILL.md
recommend-approach/
SKILL.md
merge-sources/
SKILL.md
consolidate-documents/
SKILL.md
reconcile-conflicts/
SKILL.md
retention-audit/
SKILL.md
update-page/
SKILL.md
update-section/
SKILL.md
expand-content/
SKILL.md
reorganize-content/
SKILL.md
implement-feature/
SKILL.md
fix-bug/
SKILL.md
refactor/
SKILL.md
update-bookmarklet/
SKILL.md
adversarial-test/
SKILL.md
regression-audit/
SKILL.md
specification-gap-analysis/
SKILL.md
consolidate-specification/
SKILL.md
create-handoff/
SKILL.md
capture-decisions/
SKILL.md
identify-open-questions/
SKILL.md
define-next-move/
SKILL.md
app/
agents.py ← Agent(...) definitions
tools.py ← function tools and MCP wiring
guardrails.py
run.py
workspace/
inputs/
work/
outputs/
state/
The Markdown files under agents/ can remain the canonical prose definitions and be loaded by the application into each agent's instructions. That lets the wiki summarize the definitions without becoming a second executable copy.
Example OpenAI Skill
The existing Expand Content action becomes a skill almost directly:
--- name: expand-content description: Turn brief notes or an outline into complete structured documentation when the source is correct but incomplete. --- # Expand Content Use the Technical Editor standards. 1. Preserve the author's intent and terminology. 2. Turn the supplied notes or outline into complete documentation. 3. Add context, examples, and analogies where they improve understanding. 4. Do not invent factual claims that the source does not support. 5. Keep the structure easy to navigate. 6. Write intermediate drafts to /workspace/work/. 7. Write the finished deliverable to /workspace/outputs/ when the task requires a file artifact.
A skill can also contain:
expand-content/
SKILL.md
references/
house-style.md
mediawiki-style.md
assets/
page-template.txt
scripts/
validate_headings.py
This is where the Action catalog becomes much more useful than a collection of pasted prompts. Each action can carry its own supporting knowledge and executable helpers.
Example Manager/Specialist Relationship
In the Agents SDK, the Workflow Orchestrator can keep ownership while calling a specialist as a tool:
from agents import Agent
technical_editor = Agent(
name="Technical Editor",
instructions=load_text("agents/technical-editor.md"),
)
workflow_orchestrator = Agent(
name="Workflow Orchestrator",
instructions=load_text("agents/workflow-orchestrator.md"),
tools=[
technical_editor.as_tool(
tool_name="technical_editor",
tool_description=(
"Update, expand, or reorganize structured technical "
"content while preserving meaning and terminology."
),
)
],
)
The manager decides when the Technical Editor is needed, the specialist performs its bounded work, and the manager can then call another specialist or assemble the final result.
When a specialist should take over completely, define a handoff instead.
Packaging as an OpenAI Plugin
Once the skills and integrations are stable, package the reusable capability layer as a plugin.
An OpenAI plugin can package: - Skills. - MCP server configuration. - The metadata needed to install those capabilities into compatible environments.
A minimal layout is:
primo-agent-library/
.codex-plugin/
plugin.json
.mcp.json
skills/
currentness-audit/
SKILL.md
expand-content/
SKILL.md
adversarial-test/
SKILL.md
A plugin manifest points to the skills directory and MCP configuration:
{
"name": "primo-agent-library",
"version": "1.0.0",
"description": "Reusable PRIMO.ai agent skills and integrations.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
There is one important difference from the Claude packaging model: the plugin is the capability package, not necessarily the entire application. Your explicit Agent(...) definitions and orchestration code can remain in the application while the plugin carries the portable skills and MCP integrations.
Migration Path
Step 1: Make the Catalog Executable Source
Create one source file for every agent definition and one SKILL.md directory for every action. Keep the existing names. Rewrite descriptions so they say clearly when the skill should be used, not merely what it does.
At this point, the wiki becomes documentation generated from or synchronized with the executable source rather than the master copy.
Step 2: Add the Missing Tool Layer
For each action, identify the capabilities it requires.
Examples: - Currentness Audit → web search, file retrieval, link checking. - Update Page → wiki read/write or MCP access. - Fix Bug → shell, repository files, tests, patching. - Adversarial Test → sandbox, test runner, malformed-input corpus. - Create Handoff → session history plus state files.
Do not turn these capabilities into new Actions. They are tools used by Actions.
Step 3: Build a Small Agents SDK Prototype
Start with the same two specialists that make a useful Claude test: Technical Editor and Systems Auditor. Add the Workflow Orchestrator as the manager.
This three-agent prototype exercises: - a manager, - a mostly inline/editorial workflow, - an isolated test/audit workflow, - skills, - tool permissions, - artifacts, - and manager-to-specialist delegation.
Use agent.as_tool(...) first so the Workflow Orchestrator remains responsible for the combined result.
Step 4: Add a Sandbox and Artifact Convention
Give the Systems Auditor and Software Engineer sandbox access. Establish the inputs/, work/, outputs/, and state/ directories.
Require finished files to go to /workspace/outputs. This turns "produce a document" or "fix the code" into a concrete artifact contract rather than a prose response.
Step 5: Move Durable Work to the Agents API
Once the local Agents SDK prototype behaves correctly, decide which workloads should run under the managed Agents API.
Use the Agents API when you want OpenAI to manage: - the Codex harness, - durable sessions, - context compaction, - recovery, - multi-agent subagents, - and optionally the hosted sandbox.
Use the Agents SDK when you want your own application to retain tighter control over the runtime and infrastructure.
The two approaches can share the same conceptual agent definitions, skill files, tool contracts, and workspace conventions.
Step 6: Connect Real Systems Through MCP and Plugins
Replace pasted inputs with controlled integrations: - Wiki/API or MCP access for the Technical Editor. - Repository access for the Software Engineer. - Search and retrieval for the Research Analyst. - Shared document/file sources for the Knowledge Synthesizer.
Then package stable skills and MCP configuration into the PRIMO.ai plugin.
Step 7: Add Evaluation Before Expanding the Team
Use traces to inspect routing, tool calls, handoffs, approvals, and failures. Test the same task repeatedly before promoting more catalog members to independent agents.
Only create another runtime agent when you can answer at least one of these questions with "yes": - Does it need a different tool set? - Does it need different permission or approval rules? - Does it need isolated context? - Does it need a different model or output contract? - Should it sometimes own the final response?
If not, keep it as a skill under an existing agent.
OpenAI See Also
- Agents overview (OpenAI) - Agents API (OpenAI) - Agents SDK (OpenAI) - Skills (OpenAI) - Plugins (OpenAI) - Sandbox agents (OpenAI) - Files and artifacts (OpenAI) - Orchestration and handoffs (OpenAI) - Migrate from the Claude Agent SDK to the OpenAI Agents SDK (OpenAI Cookbook)
Gemini Agent Environment
From Prompt Library to Gemini Agent Environment
The Agent and Action catalog translates directly into Google's Gemini agent stack without requiring a redesign. Google supports the open Agent Skills specification (agentskills.io), which means the exact same SKILL.md directories built for Claude Code and OpenAI work natively in Gemini tools.
Depending on whether you want an interactive terminal assistant, a code-first multi-agent pipeline, or a managed cloud runtime, the catalog maps onto three complementary Gemini layers:
- Gemini CLI for interactive local terminal work, using GEMINI.md for global workspace rules, .gemini/skills/ (or the shared .agents/skills/ alias) for on-demand action skills, and MCP-based Gemini Extensions.
- Google Agent Development Kit (ADK) for code-first multi-agent systems in Python, TypeScript, Go, or Java, offering LlmAgent specialists, deterministic workflow orchestrators (SequentialAgent, ParallelAgent, LoopAgent), progressive skill loading via SkillToolset, shared session.state, and versioned file persistence via ArtifactService.
- Vertex AI Agent Engine (or Cloud Run) when you want to deploy an ADK multi-agent system to a managed cloud runtime with persistent sessions and enterprise memory.
How the Pieces Map
| Catalog element | Gemini implementation (Gemini CLI & Google ADK) | What you gain |
|---|---|---|
| Agent definition | LlmAgent(...) in Google ADK, or a custom Gem / specialized CLI profile
|
Dedicated model choice (such as Gemini 2.5 Pro or Flash), system instructions, tools, and callbacks |
| Role (responsibility) | LlmAgent.instruction
|
The specialist's durable contract and reasoning standards |
| "Call on it when..." column | LlmAgent.description and SKILL.md frontmatter description
|
Automatic delegation to subagents and on-demand skill activation |
| Action | Skill directory containing SKILL.md in .gemini/skills/ or .agents/skills/
|
Portable, three-stage progressive disclosure across Gemini CLI and ADK |
| Agent and Action pairing | LlmAgent configured with tools=[SkillToolset(skills=[...])]
|
A specialist loads only the specific action instructions needed for the current task |
| Task-specific input | User message, multimodal types.Part inputs, or injected {state_key} placeholders
|
Native multimodal inputs (text, PDFs, audio, video, large codebases) and structured state passing |
| Recurring workspace requirements | GEMINI.md in Gemini CLI, or shared root instructions in ADK
|
House style rules apply automatically across every session and task |
| One-time output requirements | The current user message | Remains task-specific |
| Executable business action | FunctionTool, McpToolset, google_search, or BuiltInCodeExecutor
|
Live web grounding, sandboxed code execution, and external API integrations |
| Workflow Orchestrator | ADK Workflow Agents (SequentialAgent, ParallelAgent, LoopAgent) or a root LlmAgent coordinator
|
Deterministic pipelines and verification loops without relying on LLM guesswork |
| Specialist delegation | sub_agents=[...] (LLM-driven transfer_to_agent) or AgentTool(agent=...)
|
Choose between full conversational handoff and bounded tool-style invocation |
| Continuity Strategist output | session.state dictionary via output_key, plus persistent MemoryService
|
Structured step-to-step state transfer and cross-session memory |
| Finished document, spreadsheet, report, code file, etc. | Versioned types.Part saved via context.save_artifact(filename, artifact)
|
Automatic file versioning managed by InMemoryArtifactService or GcsArtifactService
|
| The reusable capability library | Gemini CLI Extension (gemini-extension.json) or shared .agents/skills/ package
|
One-command installation of skills, MCP servers, and custom slash commands |
What Makes the Gemini Architecture Distinct
Three-Level Progressive Disclosure with SkillToolset
In a traditional prompt library, giving an agent 29 actions means pasting a massive prompt or maintaining 29 separate chats. Both Gemini CLI and Google ADK's SkillToolset solve this with three-level progressive disclosure:
- Level 1 (Metadata): At startup, the agent only receives the name and description from each SKILL.md frontmatter (via the auto-generated list_skills tool). This costs roughly 100 tokens per skill and reduces baseline context usage by about 90 percent.
- Level 2 (Instructions): When a task matches a skill's description, the agent calls load_skill (or activate_skill in Gemini CLI) to pull the full SKILL.md instructions into context.
- Level 3 (Resources): Supporting files in references/, assets/, or scripts/ remain offloaded on disk until the skill's instructions tell the agent to fetch a specific file via load_skill_resource.
Both Gemini CLI and ADK also support a meta-skill pattern (skill-creator) where the agent can read the agentskills.io specification at Level 3 and author new SKILL.md folders for your library at runtime.
Deterministic Workflow Orchestrators Alongside LLM Routers
In the prompt catalog, the Workflow Orchestrator is a placeholder. Other frameworks turn the orchestrator into another LLM prompt that decides which specialist to call next. Google ADK supports LLM-driven routing through a root LlmAgent, but it also provides deterministic workflow agents that control execution flow in code without spending extra LLM tokens on routing:
- SequentialAgent: Runs a list of subagents in strict order, passing the same InvocationContext from step to step. The five-step onboarding documentation workflow in Workflow Orchestrator becomes a single SequentialAgent.
- ParallelAgent: Runs multiple subagents concurrently on the same input. For example, the Research Analyst can run Currentness Audit, Relevance Audit, and Gap Analysis in parallel and write each result to its own key in session.state.
- LoopAgent: Repeatedly runs a sequence of subagents until a quality condition is met or max_iterations is reached. This turns the catalog guideline to pair creation with verification into an automated runtime pattern: one specialist creates the work (such as Merge Sources or Implement Feature), a second specialist checks it (such as Retention Audit or Regression Audit), and the loop exits only when the audit passes.
Explicit State Passing with output_key
When several specialists collaborate in a pipeline, summarizing outputs in chat messages can drop important details. In Google ADK, every LlmAgent can declare an output_key (for example, output_key="currentness_report"). When that specialist finishes, ADK automatically writes its final response into session.state["currentness_report"].
Downstream specialists can then inject that exact output into their own instructions using curly-brace placeholders such as {currentness_report}. This gives the Knowledge Synthesizer and Technical Editor direct access to the previous step's work without relying on conversational memory.
Versioned Deliverables with ArtifactService
Google ADK separates conversational state (session.state) from file deliverables (Artifacts). An ADK Artifact is a named, versioned google.genai.types.Part object containing raw binary or text bytes and a MIME type (such as text/markdown, application/pdf, or text/csv).
Instead of dumping a 900-line MediaWiki page or a compiled report into the chat stream, a tool or callback calls await context.save_artifact(filename="Personal_Agent.wiki", artifact=part):
- Every save with the same filename automatically creates a new version number (version 0, 1, 2, and so on).
- Downstream agents such as the Systems Auditor or Knowledge Synthesizer can load specific versions via await context.load_artifact(filename="Personal_Agent.wiki") or the built-in LoadArtifactsTool.
- Storage is backed by InMemoryArtifactService during local testing or GcsArtifactService (Google Cloud Storage) for persistent production archives, and can be scoped to either the current session or the user namespace across all sessions.
Which Catalog Members Should Become Runtime Agents
| Catalog member | Recommended Gemini implementation | Reason |
|---|---|---|
| Workflow Orchestrator | SequentialAgent, ParallelAgent, LoopAgent, or root LlmAgent
|
Use deterministic workflow agents for known pipelines and a root LlmAgent for open-ended triage
|
| Research Analyst | LlmAgent with google_search and SkillToolset
|
Benefits from built-in Google Search grounding, read-only permissions, and parallel audit execution |
| Systems Auditor | LlmAgent paired in a LoopAgent with the creator agent
|
Fresh context and code execution allow it to act as an automated critic in Generator-Critic loops |
| Software Engineer | LlmAgent with BuiltInCodeExecutor or local shell/MCP tools
|
Needs code execution, repository tools, and isolated iteration |
| Knowledge Synthesizer | LlmAgent utilizing Gemini's long context window and ArtifactService
|
Can ingest large multi-document sets directly and verify completeness via LoopAgent
|
| Technical Editor | LlmAgent with SkillToolset and MediaWiki McpToolset
|
Reads audit state via {output_key} and saves finished wiki markup as a versioned artifact
|
| Solution Architect | Inline skills in Gemini CLI, or LlmAgent in ADK
|
Requirements Clarification runs interactively with the user; design actions can run as skills |
| Continuity Strategist | Skills combined with session.state, MemoryService, and handoff artifacts
|
Summarizes session.state keys and writes durable HANDOFF.md and DECISIONS.md artifacts
|
Guardrails, Callbacks, and Consent
Gemini provides explicit permission boundaries in both the terminal and the SDK:
- Gemini CLI consent prompts: In Gemini CLI, skills and MCP tools do not silently execute side effects. When a request matches a skill, Gemini CLI shows the skill name, description, and folder path and asks for activation consent before granting access to bundled scripts or resources. MCP tools that modify external data (such as creating a document or editing a wiki page) trigger an action confirmation prompt.
- ADK Callbacks as Guardrails: In Google ADK, every agent supports lifecycle callbacks including before_agent_callback, before_model_callback, before_tool_callback, and after_tool_callback. A before_tool_callback inspects the tool name and arguments before execution and can block a call, validate inputs against a policy, or require human confirmation before allowing a write operation.
Recommended Source Layout
Because Gemini CLI and Google ADK both recognize the .agents/skills/ directory convention, you can use a single skill library across Claude, OpenAI, and Gemini without duplicating a single SKILL.md file:
agent-catalog/
GEMINI.md ← shared workspace rules and house style for Gemini CLI
AGENTS.md ← shared workspace rules for OpenAI / cross-agent tools
CLAUDE.md ← shared workspace rules for Claude Code
.gemini/
settings.json ← Gemini CLI settings and MCP server wiring
agents/
workflow-orchestrator.md ← canonical specialist instructions loaded by ADK
research-analyst.md
solution-architect.md
knowledge-synthesizer.md
technical-editor.md
software-engineer.md
systems-auditor.md
continuity-strategist.md
.agents/
skills/ ← shared open-standard skills discovered by Gemini CLI & ADK
currentness-audit/
SKILL.md
relevance-audit/
SKILL.md
gap-analysis/
SKILL.md
strategic-analysis/
SKILL.md
red-team-analysis/
SKILL.md
develop-solution/
SKILL.md
explore-alternatives/
SKILL.md
requirements-clarification/
SKILL.md
recommend-approach/
SKILL.md
merge-sources/
SKILL.md
consolidate-documents/
SKILL.md
reconcile-conflicts/
SKILL.md
retention-audit/
SKILL.md
update-page/
SKILL.md
update-section/
SKILL.md
expand-content/
SKILL.md
references/
house-style.md
mediawiki-style.md
reorganize-content/
SKILL.md
implement-feature/
SKILL.md
fix-bug/
SKILL.md
refactor/
SKILL.md
update-bookmarklet/
SKILL.md
adversarial-test/
SKILL.md
regression-audit/
SKILL.md
specification-gap-analysis/
SKILL.md
consolidate-specification/
SKILL.md
create-handoff/
SKILL.md
capture-decisions/
SKILL.md
identify-open-questions/
SKILL.md
define-next-move/
SKILL.md
adk_app/
__init__.py
agent.py ← root_agent definition for `adk web` and `adk run`
workflows.py ← SequentialAgent, ParallelAgent, and LoopAgent pipelines
tools.py ← FunctionTools, Artifact savers, and McpToolset wiring
callbacks.py ← before_tool_callback guardrails
Example Google ADK Skill and Workflow Wiring
In Google ADK, you load the existing SKILL.md directories from disk using load_skill_from_dir and bundle them into a SkillToolset for each specialist. You can then wire those specialists into deterministic pipelines and save the final output as a versioned ADK Artifact:
from pathlib import Path
from google.genai import types
from google.adk.agents import LlmAgent, SequentialAgent, LoopAgent
from google.adk.skills import load_skill_from_dir
from google.adk.tools import google_search
from google.adk.tools.skill_toolset import SkillToolset
from google.adk.tools.tool_context import ToolContext
BASE_DIR = Path(__file__).resolve().parent.parent
SKILLS_DIR = BASE_DIR / ".agents" / "skills"
AGENTS_DIR = BASE_DIR / "agents"
def load_prompt(filename: str) -> str:
return (AGENTS_DIR / filename).read_text(encoding="utf-8")
def load_skills(*skill_names: str) -> SkillToolset:
skills = [load_skill_from_dir(SKILLS_DIR / name) for name in skill_names]
return SkillToolset(skills=skills)
async def save_wiki_artifact(
content: str,
filename: str = "updated_page.wiki",
tool_context: ToolContext = None,
) -> dict:
"""Saves finished MediaWiki markup as a versioned ADK Artifact."""
part = types.Part.from_bytes(
data=content.encode("utf-8"),
mime_type="text/plain",
)
version = await tool_context.save_artifact(filename=filename, artifact=part)
return {"status": "saved", "filename": filename, "version": version}
research_analyst = LlmAgent(
name="research_analyst",
model="gemini-2.5-pro",
description="Investigates, verifies facts, and audits content currentness and gaps.",
instruction=load_prompt("research-analyst.md"),
tools=[
google_search,
load_skills(
"currentness-audit",
"relevance-audit",
"gap-analysis",
"strategic-analysis",
"red-team-analysis",
),
],
output_key="audit_findings",
)
knowledge_synthesizer = LlmAgent(
name="knowledge_synthesizer",
model="gemini-2.5-pro",
description="Combines multiple sources into one coherent document and verifies retention.",
instruction=(
load_prompt("knowledge-synthesizer.md")
+ "\nIncorporate these audit findings:\n{audit_findings}"
),
tools=[
load_skills(
"merge-sources",
"consolidate-documents",
"reconcile-conflicts",
"retention-audit",
),
],
output_key="merged_draft",
)
technical_editor = LlmAgent(
name="technical_editor",
model="gemini-2.5-pro",
description="Updates, expands, and formats technical documentation and wiki pages.",
instruction=(
load_prompt("technical-editor.md")
+ "\nEdit and format this merged draft:\n{merged_draft}"
),
tools=[
load_skills("update-page", "update-section", "expand-content", "reorganize-content"),
save_wiki_artifact,
],
output_key="final_wiki_page",
)
# Deterministic pipeline for the onboarding documentation refresh workflow
refresh_docs_pipeline = SequentialAgent(
name="refresh_docs_pipeline",
description="Audits, merges, and updates multi-page documentation in sequence.",
sub_agents=[research_analyst, knowledge_synthesizer, technical_editor],
)
Packaging as a Gemini CLI Extension
Just as Claude Code and OpenAI support plugins, Gemini CLI packages reusable skills, MCP servers, and slash commands into an Extension. An extension directory contains a gemini-extension.json manifest alongside your skills:
primo-gemini-extension/
gemini-extension.json
GEMINI.md
skills/
currentness-audit/
SKILL.md
expand-content/
SKILL.md
adversarial-test/
SKILL.md
The manifest wires your MCP servers and context rules so any project or workstation can install the entire PRIMO.ai catalog with gemini extensions install or link it locally during development with gemini skills link:
{
"name": "primo-agent-library",
"version": "1.0.0",
"description": "Reusable PRIMO.ai specialist skills and MediaWiki MCP tools.",
"contextFileName": "GEMINI.md",
"mcpServers": {
"mediawiki": {
"command": "python",
"args": ["-m", "mcp_mediawiki_server"]
}
}
}
Migration Path
Step 1: Unify Your Action Library in .agents/skills/
Place all 29 action folders inside .agents/skills/ with valid YAML frontmatter (name and description) in each SKILL.md file. Because Gemini CLI, Google ADK, Claude Code, and OpenAI all read this directory convention, you maintain one single copy of your actions across every vendor. Put your recurring output rules (active voice, conversational tone, no em dashes, MediaWiki formatting) into GEMINI.md.
Step 2: Test Specialist Personas in Google AI Studio or Gems
Before writing orchestration code, test your 7 specialist definitions in Google AI Studio or as custom Gems in the Gemini web app. Enable Grounding with Google Search for the Research Analyst and Code Execution for the Software Engineer and Systems Auditor. This validates your specialist instructions and tool behavior with zero setup.
Step 3: Run Interactive Workflows in Gemini CLI
Open Gemini CLI in your project directory. Gemini CLI automatically loads GEMINI.md and discovers the skills inside .agents/skills/.
- Run /skills list to verify that all 29 actions are discovered.
- Test natural requests to verify that your description fields trigger the right skill via progressive disclosure.
- Use the built-in skill-creator skill whenever you want Gemini to draft a new action folder from a conversational description.
Step 4: Build Deterministic Pipelines in Google ADK
Install the Agent Development Kit (pip install google-adk) and wire your first multi-agent workflow in Python:
- Start with Research Analyst, Technical Editor, and Systems Auditor as LlmAgent instances equipped with SkillToolset.
- Connect sequential steps using SequentialAgent and pass outputs explicitly via output_key and {state_key} placeholders.
- Wrap creation and verification pairs (such as Merge Sources + Retention Audit, or Implement Feature + Regression Audit) inside a LoopAgent so the audit runs automatically after creation.
- Run adk web locally to open the ADK visual debugger, where you can inspect every event, skill activation, state change, and tool call.
Step 5: Add ArtifactService, Guardrails, and MCP Integrations
- Configure InMemoryArtifactService (for local runs) or GcsArtifactService (for durable cloud storage) on your ADK Runner so finished wiki pages, code files, and reports are saved and versioned via context.save_artifact().
- Connect your MediaWiki API and local repositories using McpToolset.
- Add a before_tool_callback guardrail so read-only tools execute freely while write operations (such as updating a live page on PRIMO.ai) require explicit confirmation.
- When a workflow needs to run as an always-on service, deploy the ADK application to Vertex AI Agent Engine or Google Cloud Run.
Gemini See Also
- Agent Development Kit (ADK) Documentation (Google) - Artifacts in Agent Development Kit (Google ADK) - Developer's Guide to Building ADK Agents with Skills (Google Developers Blog) - Google ADK Recipes and Sample Agents (GitHub) - Using Agent Skills in Gemini CLI (Gemini CLI Documentation) - Gemini CLI Extensions Directory (Gemini CLI) - Agent Skills Open Specification (agentskills.io)