워크플로, 템플릿, 프로젝트 및 구성을 생성하고 테스트하여 승인된 솔루션 설계를 구현합니다.
- GitHub 스타
- 18
- 파일
- 75
- 마지막 커밋
- 2026년 11월 5일
- 라이선스
- GPL-3.0
- 허용된 도구
- —
builder-agent skill은 무엇을 하나요?
워크플로, 템플릿, 프로젝트 및 구성을 생성하고 테스트하여 승인된 솔루션 설계를 구현합니다.
skill의 SKILL.md에서 생성된 요약입니다.
builder-agent skill 정보
승인된 솔루션 설계를 실제 작동하는 자동화로 구현하는 것이 이 SKILL의 주요 기능입니다. 이 SKILL은 최종 확정된 solution-design.md를 바탕으로 해당 사양을 워크플로, 템플릿, 프로젝트, 구성과 같은 배포 자산으로 변환해야 하는 엔지니어를 위해 설계되었습니다. agent는 제공된 워스페이스 내에서 작동하며, bootstrap 정보를 다시 가져올 필요 없이 일관성을 유지하기 위해 tasks.json, apps.json, adapters.json과 같은 기존 discovery 데이터를 활용합니다.
빌드 프로세스 동안 agent는 개별 작업과 워크플로가 올바르게 실행되고 변수가 적절하게 연결되었는지 확인하기 위해 컴포넌트 수준의 테스트를 수행합니다. 또한 부모 및 자식 agent 구조를 분해하고 자식 agent를 먼저 빌드하는 특정 라이프사이클을 따라 복잡한 빌드를 관리합니다. 환경 파일에 자격 증명이 있는 경우 OAuth를 통한 인증 bootstrap도 처리합니다. 모든 구성 요소가 개별적으로 검증되고 asset ID가 use-case-memory.md 파일에 기록되면, agent는 공식 수락 테스트를 위해 프로젝트를 qa-agent에게 전달합니다.
agent가 수행할 수 있는 작업
- 1도구로서의 자식 agent 빌드특정 FlowAI 패턴에 따라 자식 agent를 생성하고 이를 부모 agent에 도구로 연결합니다.
- 2빌드 컨텍스트 유지메모리 파일을 사용하여 여러 세션에 걸쳐 아키텍처 결정, asset ID 및 프로젝트 상태를 추적합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
builder-agent skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 builder-agent skill 설치
/plugin marketplace add itential/builder-skills /plugin install itential-builder@itential-builder
Claude Code에 builder-agent skill 설치
~/.claude/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.claude/skills/builder-agentClaude Code (project)에 builder-agent skill 설치
.claude/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent .claude/skills/builder-agentCodex에 builder-agent skill 설치
~/.agents/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.agents/skills/builder-agentGemini CLI에 builder-agent skill 설치
~/.gemini/skills/builder-agent/SKILL.md
$ npx degit itential/builder-skills/skills/builder-agent ~/.gemini/skills/builder-agentClaude.ai에 builder-agent skill 설치
npx degit itential/builder-skills/skills/builder-agent builder-agent && zip -r builder-agent.zip builder-agent # claude.ai → Customize → Skills → + → Create skill → Upload a skill → builder-agent.zip
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능itential/builder-skills/skills/builder-agent is public and reachablegithub.com/itential/builder-skills/tree/HEAD/skills/builder- ↗통과
- 오픈 소스 라이선스 (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-05github.com/itential/builder-skills/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음5 scripts read; no download-and-run, remote eval, base64 execution or credential upload통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/itential/builder-skills/blob/HEAD/skills/builder- ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/itential/builder-skills/blob/HEAD/skills/builder- ↗통과
- SKILL.md가 Agent Skills 형식을 따름SKILL.md is 2888 lines; the spec suggests under 500github.com/itential/builder-skills/blob/HEAD/skills/builder- ↗결함 발견
SKILL.md
GitHub에서 보기Builder Agent
Stage: Build
Owns: Implementing the approved design.
Receives from: /solution-arch-agent (approved solution-design.md + complete workspace)
Produces: Deployed assets (workflows, templates, projects)
Hands off to: /qa-agent (acceptance testing + as-built record)
Customization
Before using this skill, check custom/org/, custom/team/ and custom/dev/
in this skill's own folder. Read every .md file found — any folder may be
empty or absent. Apply them on top of everything below; where a file overrides a
specific rule here, follow the override. More specific wins: dev > team > org >
this document. No customization may weaken this skill's safety
rules or put credentials in committed files.
Bundled files: paths in this skill that start with assets/ or scripts/ are
relative to this skill's own folder. When you read one, or pass one to a shell
command (which runs from the user's working folder), use this skill's folder +
that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.
Stage Expectations
Build
| Engineer provides | Approved solution-design.md (all platform data already present in workspace) |
| Agent does | Builds all components per design, tests each piece individually, reports delivery outcomes |
| Engineer action | Reviews delivery and resolves open build questions |
| Deliverable | Deployed assets (workflows, templates, projects) |
| Customer receives | Delivered project — all workflows, templates, and configs individually tested, packaged, and access granted. Formal acceptance testing and sign-off happen next, in /qa-agent. |
Build implements the approved plan. The builder never re-pulls discovery data — it uses what the Solution Architecture Agent left in the workspace. If any required file is missing, stop and surface as an upstream failure.
Testing during Build is component-level, not acceptance-level. "Test each piece" here means confirming a task or workflow runs without error and wires variables correctly — not verifying the delivered solution satisfies the customer's stated acceptance criteria end-to-end. That's /qa-agent's job, running against the completed build with real test data the engineer confirms. Don't skip component testing because "QA will catch it" — a structurally broken workflow wastes a live acceptance-test run.
This skill covers everything needed to build and test Itential automation assets: projects, workflows, templates, and command templates.
FlowAI agents: load /flowagent before building agents. When the design has
a parent agent that calls child agents, build each child as its own agent, then
attach it to the parent as an agent:<child-id> tool, following "Agents as tools"
in /flowagent. Don't wrap the agents in a
workflow or runCode unless the design says to. The workflow and childJob steps
below apply to workflow components only. When you test, run the child on its own
and then through the parent. Record both session IDs, and check the child's
answer, not just the parent's tool status.
Phases built agent first (Section C of the design says "Agent first"): build
the agent and run the test sessions the implementation plan names. Once they meet
the plan's definition of proven and the engineer agrees, record the session IDs in
use-case-memory.md and hand off to /flowagent-to-spec for that phase. Its
<phase>-converted-spec.md comes back through /solution-arch-agent design-only
before the deterministic assets are built — don't build them from the agent
directly. Meanwhile, build the delivery's other phases as designed.
Workspace Contract
The builder receives a complete workspace. All discovery data is already present. Solution-design (or setup for explore mode) has already pulled everything.
Required files (must exist before build starts):
{use-case}/
.auth.json ← auth token
.env ← credentials (for re-auth if token expires)
openapi.json ← API reference (pulled by solution-arch-agent or explore)
tasks.json ← task catalog (pulled by solution-arch-agent or explore)
apps.json ← app/adapter type names (pulled by solution-arch-agent or explore)
adapters.json ← adapter instances (pulled by solution-arch-agent or explore)
applications.json ← app health (pulled by solution-arch-agent or explore)
May also exist (spec-contingent):
use-case-memory.md ← living context: IDs, decisions, gotchas, open items — READ THIS FIRST
customer-spec.md ← approved HLD (Requirements)
feasibility.md ← approved feasibility assessment
customer-context.md ← business rules (if provided)
solution-design.md ← approved Solution Design / LLD
devices.json ← device inventory
workflows.json ← existing workflows
device-groups.json ← device groups
task-schemas.json ← fetched on demand during build (append-only, never pre-populated)
test-report.md ← if returning from /qa-agent with a failing test case — has the exact case ID, expected vs actual, and evidence
The builder NEVER re-pulls bootstrap or discovery data. If tasks.json, apps.json, or adapters.json is missing, stop and tell the user — that's an upstream failure, not something to silently fix.
Exception — .auth.json bootstrap: If .auth.json is missing but .env exists with AUTH_METHOD=oauth, CLIENT_ID, and CLIENT_SECRET, the builder MUST authenticate and create .auth.json before proceeding — do NOT stop and report an upstream failure. See the Bootstrap Authentication section below.
The only API calls the builder makes are:
- Auth bootstrap — POST /oauth/token when
.auth.jsonis missing (see below) - Create — POST workflows, templates, projects
- Update — PUT to edit assets
- Test — POST jobs/start, GET job status
- Schema fetch — task schemas not yet in
task-schemas.json(append to file after fetching) - Re-auth — if token expires, use
.envto refresh.auth.json - FlowAI agents — create and update agents, read tools (
GET /tools/...), start test sessions, and read sessions and their messages. Never complete a WorkCenter work item; that's the assigned person's job.
Bootstrap Authentication
When .auth.json is missing but .env has AUTH_METHOD=oauth with CLIENT_ID and CLIENT_SECRET, authenticate automatically before proceeding.
The correct Itential SaaS/Cloud OAuth endpoint is:
POST {PLATFORM_URL}/oauth/token
Content-Type: application/x-www-form-urlencoded
Body (form-encoded, NOT JSON — JSON returns 415):
grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}
Critical:
- Content-Type MUST be
application/x-www-form-urlencoded— NOTapplication/json. Sending JSON returns HTTP 415. - The
/loginendpoint does NOT support OAuth client credentials on SaaS instances — always use/oauth/token. - On success, write
.auth.jsonwith the token so all subsequent API calls just work.
Build Lifecycle
0. Memory file → create or read {use-case}/use-case-memory.md
1. Decompose → identify parent/child split before writing any code
2. Create project → container for all assets
3. Discover tasks → search tasks.json, fetch schemas
4. Build children first → each child workflow independently testable
5. Build templates → Jinja2 (config gen) or TextFSM (output parsing)
6. Build command templates → MOP pre/post checks with validation rules
7. Build orchestrator last → parent wires tested children via childJob
8. Add assets to project → move/copy into the project
9. Set project membership → resolve spec members, PATCH immediately after import
10. Test each component → jobs/start, check results (component-level, not acceptance-level)
11. Debug → check job.error, filesystem-first
12. Reconcile → diff built vs designed, update artifacts
13. Update memory file → record IDs, decisions, gotchas, test results, open items
14. Update this skill → if you hit a platform behavior not documented here, add it before closing out
15. Hand off to /qa-agent → build is complete; real IDs are in solution-design.md §D
Step 0 — memory file:
At the start of every session, check for {use-case}/use-case-memory.md ({use-case} = use-cases/<use-case-name>/ in the working folder):
- Exists → read it before doing anything else. It tells you the platform, project ID, what's already built, decisions made, and open items. Don't re-discover what's already documented.
- Missing → create it now from
assets/helpers/use-case-memory.mdtemplate. Fill in Platform URL,Stage: build,Status: activeimmediately.
Step 13 — update memory file after every session:
Before closing out any build session, update use-case-memory.md with:
- Any new asset IDs (project ID, workflow UUIDs, transformation IDs, adapter names)
- Any architectural decisions made and why
- Any gotchas hit and how they were fixed
- Test results (date, what was tested, outcome)
- Updated open items list
StageandStatusif they changed — mid-build,Stagestaysbuild; only update it totestat the Step 15 handoff
The memory file is what makes it possible to pick up a use-case after weeks without re-discovering everything from scratch.
Step 14 — how to update this skill:
- New platform behavior (error shape, field constraint, task gotcha) → add detail to the relevant body section (
### query,### childJob,### Projects, etc.), then add a one-liner to the Gotchas pre-flight list under the right category. - New pattern or workflow recipe → add to
## Workflow Patternsand, if the pattern is reusable, export the project from the platform and, in a clone of the builder-skills repo, save it to the shared library atassets/helpers/assets/(CI bundles it into this skill asassets/helpers/assets/). Add a row to the Helper Templates table in this file pointing to it. - Do NOT create a new top-level section for a single finding — put it where a builder would look when working on that topic.
Step 15 — hand off to /qa-agent: Once every component has been individually tested and solution-design.md Section D has real IDs (project ID, workflow IDs) instead of placeholders, the build is complete. Update use-case-memory.md to Stage: test before ending the session. Tell the engineer the build is done and route to /qa-agent for acceptance testing and the as-built record — don't write as-built.md here.
If /qa-agent hands back a failing test case: fix the specific issue it identifies (it gives you the case ID, expected vs. actual, and evidence — a job ID or static-check output). Don't re-examine the whole build; the failure report tells you exactly what broke. Once fixed, tell the engineer so /qa-agent can re-run just that case.
Pending Integration Pattern
Use this pattern when the solution design includes ⚠ Stub integrations — adapters that are required but not yet installed on the platform, or whose connection details (hostname, auth method, credentials) are still being confirmed by the customer.
Goal: deliver a fully buildable, testable project now. The customer sees real workflows and real progress. When the adapter arrives, swapping in the real task is a single targeted update.
Stub Workflow (stub-{integration-name})
Build one stub workflow per pending integration. It exercises one core connectivity action — enough to prove the integration wires up correctly end-to-end when the adapter is provisioned.
Structure:
workflow_start
→ buildPayload (newVariable — assembles minimum input for the core action)
→ callIntegration (newVariable placeholder — sets {integrationName}Status = "pending_adapter")
↓ error
→ workflow_end
workflow_end
Rules:
buildPayload—newVariabletask. Assembles the minimum required input per theintegration-model-{name}.json(e.g., for Slack:{channel, text}). No adapter dependency — always runnable without a real adapter.callIntegration—newVariableplaceholder. Sets{integrationName}Status = "pending_adapter". Use the hex task ID that the real adapter task will occupy. Error transition pre-wired toworkflow_end.- One input variable:
dryRun(boolean, defaulttrue). Stub ignores it; activated workflow can use it to skip side effects during testing. - Add all stub workflows to the same project as the main delivery workflows.
Choosing the core action:
- Prefer the simplest write/action that validates auth end-to-end (post a message, launch a job, write a secret)
- If the integration is read-only in this use case, use a lightweight read (get current user, health check)
- Derive the request payload from
integration-model-{name}.json— that file is the contract
Placeholder Task (in any workflow)
When a workflow needs to call an adapter that isn't installed, replace the real adapter task with a newVariable placeholder — same position, same task ID, same transitions:
- Use a
newVariabletask in the exact slot the real adapter task will occupy - Assign the same hex task ID the real task will use when activated
- Set variable:
{integrationName}Status = "pending_adapter"— machine-readable pending state - Wire all transitions identically (including the error transition) to how the real task will be wired
As-Built: Activate Integration Section
For every pending integration, include a dedicated section in as-built.md:
## Activate: {Integration Name}
When the {AdapterType} adapter is provisioned:
1. Confirm adapter instance name:
jq '.results[] | select(.package_id | test("{name}";"i")) | {id,state}' adapters.json
2. Replace task `{taskId}` in workflow `{workflowId}` with:
(complete replacement task JSON — all fields pre-filled from integration-model-{name}.json,
app and locationType set to the adapter type name, incoming variables wired from the workflow)
Only field left blank: `adapter_id`. Fill from step 1.
3. Verify exact field names from the live schema before activating:
POST /automation-studio/multipleTaskDetails?dereferenceSchemas=true
body: {"tasks": [{"name": "{taskName}", "app": "{appType}"}]}
This pattern works for both standard Itential adapters (EmailOpensource, Slack) and custom OpenAPI virtual integrations. The integration-model-{name}.json file is the contract in both cases.
Guides
Building a Gateway4 → Gateway5 migration? Follow assets/helpers/gateway-migration/conversion-guide.md
for each item's pattern (inventory with broker actions, services imported through Gateway Manager,
task-by-task rewire, re-pointing every consumer of a Gateway4 output), and import the migrated
workflows as a new project — never edit the originals.
Guide 1: Build a workflow end-to-end
Follow these steps in order. Do not skip any step.
Before writing task JSON, extract a real example from
assets/helpers/assets/— do not invent task structure from memory. (assets/helpers/create/is for API wrappers only — project/workflow creation endpoints, not task bodies.)# 1. Find which asset project matches your use case ls assets/helpers/assets/ # 2. Extract the workflow most similar to what you're building jq '[.components[] | select(.type=="workflow")] | .[].document.name' \ assets/helpers/assets/vendor-servicenow.json # 3. Read its full task map — this is your reference jq '[.components[] | select(.type=="workflow") | select(.document.name | test("WORKFLOW_NAME"; "i"))] | first | .document | {tasks, transitions}' \ assets/helpers/assets/vendor-servicenow.json # 4. Extract the specific task type you need jq '[.components[].document.tasks // {} | to_entries[] | select(.value.name == "TASK_NAME")] | first | .value' \ assets/helpers/assets/vendor-servicenow.jsonReplace
assets/helpers/assets/vendor-servicenow.jsonwith whichever asset file best matches your use case:
- Adapter tasks (ServiceNow, Infoblox) →
assets/helpers/assets/vendor-servicenow.json,assets/helpers/assets/vendor-infoblox-nios-ddi.json- Network device tasks (CLI, MOP) →
assets/helpers/assets/vendor-cisco-ios.json,assets/helpers/assets/vendor-arista-eos.json,assets/helpers/assets/vendor-juniper-junos.json- IPAM/inventory →
assets/helpers/assets/vendor-netbox.json- Data transformations →
assets/helpers/assets/itential-platform-data-manipulation.json- Config management (RunCommandTemplate, itential_cli) →
assets/helpers/assets/itential-platform-configuration-management.json- LCM action workflows →
assets/helpers/assets/lcm/lcm-vxlan-fabric-services-project.json
Step 0: Decompose before you build.
Before writing any JSON, identify the parent/child split from the solution design. Ask for each phase:
- Can this phase be run and tested on its own? → Child workflow
- Does it loop over multiple items (devices, records)? → Child workflow with
loopType - Is it reusable across other use cases? → Child workflow
- Is it a simple sequential step with no independent test value? → Task in orchestrator
Build order is always: children first, orchestrator last. The orchestrator is just childJob calls to tested children — it should not contain raw adapter tasks unless there is no logical way to split.
Step 0a: Before building a per-item transform loop, default to runCode + Enable Query instead of chaining WorkFlowEngine utility tasks.
If a phase does ANY of the following, don't reach for forEach + query×N + evaluation + newVariable + merge + push/objectToString/join/makeData — build it as a single runCode (Python, GatewayManager) task instead:
- Loops over a list, extracting 2+ fields per item
- Branches per item on a field value (manufacturer, status, type) to pick between two or more output shapes
- Reshapes each item into a different structure before handing it to the next task
When NOT to use runCode: the per-item work needs to call another platform task (adapter, app method, childJob) for each item — runCode only runs Python against the data payload it's given; it cannot invoke other Itential tasks. Use forEach+childJob/adapter-task for that instead.
See the ### runCode section under Utility Tasks below for the collapse story, field reference, and the exact jq commands to extract a verified real example before building any transform loop.
Read a full workflow from asset projects before building any multi-workflow solution:
# Parent → childJob → evaluation pattern
jq '[.components[] | select(.type=="workflow") | select(.document.name | test("Upgrade|Runner"))] | first | .document | {name,tasks,transitions}' \
assets/helpers/assets/vendor-cisco-ios.json
이 스킬의 파일
75builder-agent skill 질문
Claude Code에 builder-agent skill을 어떻게 설치하나요?
npx degit itential/builder-skills/skills/builder-agent ~/.claude/skills/builder-agent를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
builder-agent skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
인증 파일이 없는 경우 builder agent는 어떻게 해야 하나요?
.auth.json 파일이 없더라도 .env에 유효한 OAuth 자격 증명이 포함되어 있다면, agent는 작업을 진행하기 전에 자동으로 인증을 수행하고 파일을 생성해야 합니다.
builder agent가 엔드 투 엔드(end-to-end) 수락 테스트를 수행하나요?
아니요, builder는 개별 구성 요소가 올바르게 작동하는지 확인하기 위해 컴포넌트 수준의 테스트를 수행합니다. 수락 테스트는 /qa-agent가 담당합니다.