kayforkind/skill-slice/agents-sdk
Claude Code and agent skill by kayforkind/skill-slice
- community
Checking that the SKILL.md file is still in the repository.
Build, run, deploy, and evaluate OpenAI Agents SDK apps. Use when the user asks to create or adapt an Agents SDK app, build from a prompt or Codex thread, prepare a runnable agent prototype, add a focused eval harness, or deploy locally through the Agents SDK Deployment Manager. Not for LangChain/CrewAI or generic Chat Completions wrappers without the OpenAI Agents SDK.
Install
npx vskill@latest install kayforkind/skill-slice/agents-sdkSKILL.md
The same SKILL.md was published earlier as kayforkind/skill-slice/agents-sdk.
When to Use
Use this skill when the user asks to:
- Create a new runnable OpenAI Agents SDK app from an idea, prompt, or prior Codex thread.
- Adapt an existing repo or demo by adding the smallest Agents SDK layer needed to make the workflow agentic.
- Add a focused local eval harness against the real agent path.
- Deploy an existing or newly built Agents SDK app locally through the Deployment Manager.
- Turn prior Codex work (thread IDs, session links, rollout JSONL paths, pasted summaries) into a build brief and then a working app.
Prefer Python unless the user explicitly asks for TypeScript.
Prerequisites
- API key: Agents SDK apps require
OPENAI_API_KEYto run. Before building, running, or testing an app that calls the OpenAI API, use theopenai-platform-api-keyskill in this plugin as the credential gate. Follow that skill's confirmation flow. Never print, summarize, or commit secret values. - Docs gate: Read the Agents guide before creating or changing any Agents SDK implementation. Read the Sandbox Agents guide before choosing
SandboxAgent, workspace manifests, shell/file access, skills, or sandbox backend behavior. If a docs MCP/tool is unavailable, read the official docs URLs directly instead of skipping the docs gate. - Package manager: For Python projects, prefer
uv. Addopenai-agentswhen the project owns dependencies. - Windows host (primary): Commands below that use
$VARor$HOMEare POSIX shell forms used by the Deployment Manager Makefile. On a Windows PowerShell host, set environment variables with$env:VAR = "value"and reference paths with backslash or forward-slash forms as appropriate. When invokingmake, run it in a POSIX-compatible shell (Git Bash, WSL) because the Deployment Manager Makefile uses POSIX syntax.
References
Load these reference files and URLs at the specific points noted:
- Agents guide —
https://developers.openai.com/api/docs/guides/agents— Read before creating or changing any Agents SDK implementation. - Sandbox Agents guide —
https://developers.openai.com/api/docs/guides/agents/sandboxes— Read before choosing `SandboxAgent`, workspace manifests, shell/file access, skills, or sandbox backend behavior. - Python SDK —
https://github.com/openai/openai-agents-python— Follow for packaging, naming, and command conventions in Python projects. - TypeScript SDK —
https://github.com/openai/openai-agents-js— Follow only when the user asks for TypeScript. - Deployment Manager —
https://github.com/openai/openai-cookbook/tree/main/examples/agents_sdk/deployment_manager— Read before deploying; verify$MANAGER_DIR/Makefileexists before invokingmake. - Agent evals guide —
https://developers.openai.com/api/docs/guides/agent-evals— Read before creating or changing evals or generating platform eval configs, grader JSON, or dataset upload scripts. Also read trace grading, evals, and graders docs before those specific artifacts.
If a docs MCP/tool is unavailable, read the official docs URLs directly instead of skipping the docs gate.
Procedure
1. Intake — classify the request before editing
- New app from prompt or idea: Build the smallest runnable Agents SDK app that proves the workflow.
- Existing app or demo: Inspect the repo and add the smallest Agents SDK layer needed to make the workflow agentic.
- Prior Codex work: Turn thread IDs, session links, rollout JSONL paths, or pasted summaries into a short build brief before writing code.
- Evals request: Add a focused local eval harness against the real agent path.
- Deployment-only request: Deploy the existing app without rebuilding unless deployment reveals a small required fix.
2. Inspect the target repo
Read README.md, dependency files, app entrypoints, existing examples, and any domain-specific skills/ or policy files.
3. Define the app contract
Capture the agent goal, input shape, expected output, tools, state, approval gates, and the local command that proves the workflow.
4. Set up dependencies
Use the repo's existing package manager. For Python projects, prefer uv; add openai-agents when the project owns dependencies.
5. Start with one agent
Use a single Agent with clear static instructions and Runner.run until the workflow proves it needs specialists, handoffs, structured outputs, or sandbox execution.
6. Add tools deliberately
Use @function_tool for deterministic local actions such as lookups, calculations, file transforms, API calls, or validation. Keep side effects narrow and schemas explicit.
7. Add sandbox only for workspace tasks
Use SandboxAgent when the agent must inspect files, run shell commands, use workspace skills, or create artifacts in an isolated environment. Keep ordinary business workflows on normal Agent plus tools. Read the Sandbox Agents guide before this step.
8. Make it runnable
Provide a local smoke command, sample input, and expected observable output. If there is a UI, wire it to the agent path and verify the core workflow, not just rendering.
For HTTP apps that may be deployed:
- Make
uv run python main.pystart the web service whenPORTis present. - Keep CLI-only smoke behavior behind explicit arguments or the no-
PORTpath. - Expose
/healthfor readiness.
9. Recommended project layout
For every new prototype or substantial app build, prefer:
Generate diagrams directly as PNG files. Do not create SVG diagram sources or rely on browser screenshots of SVGs unless the user explicitly asks for editable vector sources. For one-off diagram generation, prefer a small generate_diagrams.py at the app root and run extra drawing dependencies with uv run --no-project --with ... so the app dependency file stays focused. This folder does not ship that helper.
10. Build from Codex (when source is prior Codex work)
Create a compact brief before building:
- Confirmed facts from the source threads.
- Inferences and open questions.
- App goal, agent behavior, tools, state, UI, approvals, sandbox needs, and deployment assumptions.
- A standalone build prompt that can drive the implementation.
Prefer the newest user direction when threads conflict. Keep secrets out of the brief and mention missing environment variable names only.
If the user already asked to build after planning, continue from the brief into the build workflow. Otherwise ask for approval before implementing.
11. Eval workflow
Add evals when requested. Default to a local harness that exercises the real agent workflow rather than a mock or contract-only path.
Before creating or changing evals, read the Agents guide and Agent evals guide. Read trace grading, evals, and graders docs before generating platform eval configs, grader JSON, or dataset upload scripts.
Prefer an evals/ folder unless the repo already has a stronger convention:
Design a small case matrix around meaningful behavior: happy path, missing evidence, escalation boundary, required or forbidden tool calls, approval gates, state updates, and regressions from observed bugs. Grade behavior such as structured output, tool calls, handoffs, guardrails, trace IDs, event logs, state changes, and approval behavior instead of volatile IDs or exact prose unless wording is contractual.
evals/run_local.py should:
- Load cases from
cases.jsonl. - Add the app root to
sys.path. - Run each case through the app's real agent path.
- Isolate or reset state between cases.
- Require needed environment variable names up front.
- Write
evals/results/latest.json. - Exit non-zero on failures.
12. Deploy workflow
Use the Deployment Manager from openai-cookbook for local deployments. Default to local-docker unless the user or app requires a different local target.
12a. Check deployable app signals
- An app/orchestrator entrypoint, usually
main.py. - Dependency metadata, preferably
pyproject.toml. openai-agentsin the app dependencies.PORTsupport for local app startup, withuv run python main.pystarting the HTTP service whenPORTis set./healthreadiness endpoint.- Optional
SANDBOX_BACKENDsupport for sandbox-backed apps. - Optional
docs/prompt.md,docs/agent-interactions.png, anddocs/agent-sequence.pngfor manager app details.
12b. Resolve the manager directory
- Prefer
DEPLOYMENT_MANAGER_ROOTwhen set. - Otherwise use
$HOME/code/openai-cookbook/examples/agents_sdk/deployment_manager. - If the cookbook checkout is missing, clone
https://github.com/openai/openai-cookbook. - If it exists, update it with
git pull --ff-onlyunless the user asked to avoid updating local checkouts. - Stop and report local changes or diverged history instead of forcing the checkout. Do not force-push or discard user local changes.
- Verify
$MANAGER_DIR/Makefileexists before deploying.
On Windows PowerShell, set the manager directory explicitly:
12c. Deploy through the manager
Useful options:
12d. Let the manager own extraction and deployment records
The helper imports the project, creates or reuses a matching deployment, starts it, and prints JSON with manager_url, deployment, and app_url. For local-docker, it may generate or reuse an app-level Dockerfile. If that changes the app worktree, report it and do not revert user files.
12e. Verify the result
Check manager health, the app /health readiness endpoint, and deployment sessions/containers when available.
Run git -C <app-path> status --short when the app path is inside a git checkout so generated Dockerfiles or other local edits are visible.
Pitfalls
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/agents-sdk/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/kayforkind/skill-slice/agents-sdk)