{"id":"869dd605-2a65-4344-bdec-d171901a1202","shortId":"U9AHDx","kind":"skill","title":"agent-scaffolder","tagline":"Generate a runnable Python project from an Agent Build Spec. Turns architecture documents into working code with a controller loop, tool stubs, session state, permission checks, and observability.","description":"# Agent Scaffolder\n\n## When To Use This Skill\nUse this skill when:\n- You have an Agent Build Spec (from the production agent architecture skill or written by hand).\n- You want to turn that spec into a runnable Python project, not just documentation.\n- You want a starting point that already has the right architecture: loop, tools, permissions, state, logging.\n\n## Prerequisites\nThe input should be an Agent Build Spec with at least these sections:\n- Domain and user goal\n- Tools (names and descriptions)\n- Session state (fields)\n- Permissions and approvals (which tools are auto-allow, ask-first, deny)\n- Controller loop (steps)\n\n## Output Structure\n\nGenerate a Python project with this layout:\n\n```\nyour-agent/\n  src/\n    __init__.py\n    agent.py          # Controller loop\n    tools.py          # Tool contracts and executor stubs\n    state.py          # Session state dataclass\n    permissions.py    # Runtime permission policy\n    observability.py  # Structured JSON logging\n    main.py           # CLI entry point\n  requirements.txt\n  README.md\n```\n\n## File-By-File Instructions\n\n### src/state.py\n\nDefine a `SessionState` dataclass with:\n- Every field from the spec's \"Session state\" section, typed appropriately.\n- A `session_id` field (auto-generated UUID).\n- A `turn_count` integer.\n- A `tool_history` list for recording every tool call.\n- A `completed` boolean and `failure_reason` optional string.\n- Token tracking: `total_input_tokens` and `total_output_tokens`.\n- A `record_tool_call()` method and a `summary()` method.\n\nUse `dataclasses.dataclass` with `field(default_factory=...)` for mutable defaults.\n\n### src/tools.py\n\nFor each tool in the spec:\n1. Define a tool contract dict with: `name`, `description`, `input_schema` (JSON Schema), `permission` (from the spec), `timeout_seconds`, and `side_effects`.\n2. Define a mock executor function `_exec_{tool_name}(inp: dict) -> dict` that returns realistic placeholder data.\n3. Collect all contracts in a `TOOL_CONTRACTS` list.\n4. Provide a `_anthropic_tools()` function that converts contracts to Anthropic API format.\n5. Provide an `execute_tool(tool_name, raw_input) -> (json_result, latency_ms)` function.\n\nMark the mock executors clearly so users know where to plug in real integrations.\n\n### src/permissions.py\n\nDefine:\n- A `PermissionLevel` enum: `AUTO_ALLOW`, `ASK_FIRST`, `DENY`.\n- A `check_permission(tool_name) -> PermissionLevel` function that reads from the tool contracts.\n- A `request_human_approval(tool_name, tool_input) -> bool` function using CLI input (with a comment noting this should be replaced with Slack, web UI, etc. in production).\n\n### src/observability.py\n\nDefine structured JSON logging functions:\n- `log_event(event_type, data, session_id)` — base logger to stderr.\n- `log_tool_call(session_id, turn, tool_name, latency_ms, success, error)`.\n- `log_approval(session_id, turn, tool_name, approved)`.\n- `log_turn(session_id, turn, input_tokens, output_tokens)`.\n- `log_session_end(session_id, summary)`.\n\n### src/agent.py\n\nThis is the core. Generate:\n\n1. A `SYSTEM_PROMPT` string that:\n   - Describes the agent's role from the spec's Domain section.\n   - Lists rules derived from the spec's Permissions, Stop conditions, and Core workflow.\n   - Includes `{tool_names}` and `{state_summary}` template variables.\n\n2. A `_build_system_prompt(state) -> str` function.\n\n3. A `run_agent(user_goal, **kwargs) -> SessionState` function implementing:\n   - Initialize the Anthropic client and session state.\n   - Loop up to `MAX_TURNS`:\n     - Build the system prompt with current state.\n     - Call `client.messages.create()` with system, tools, and messages.\n     - Track token usage.\n     - If the model returned no tool calls, print the final response and break.\n     - For each tool call:\n       - Check permission via `permissions.check_permission()`.\n       - If DENY, return error to model.\n       - If ASK_FIRST, call `request_human_approval()`. On denial, stop.\n       - If allowed, call `tools.execute_tool()`.\n       - Log everything via `observability`.\n       - Update session state with domain-specific results.\n     - Check stop conditions.\n   - Return final session state.\n\n### src/main.py\n\nA simple CLI using `argparse`:\n- Positional `goal` argument with a sensible default.\n- Any domain-specific flags (e.g., `--campaign`, `--repo`, `--ticket`).\n- Call `run_agent()` and print the session summary.\n\n### requirements.txt\n\n```\nanthropic>=0.42.0\n```\n\n### README.md\n\nInclude:\n- One-paragraph description of what this agent does.\n- Quick start: install, set API key, run.\n- Architecture overview: which file does what.\n- How to adapt: replace tool executors, update system prompt, adjust permissions.\n- Environment variables table.\n\n## Style Rules\n\n- Use type hints everywhere.\n- Use `from __future__ import annotations` in every file.\n- No comments that just narrate what the code does. Only explain non-obvious decisions.\n- Keep the controller loop in `agent.py` clean and readable; push details into other modules.\n- Mock executors should return data that looks realistic for the domain.\n\n## What NOT To Do\n\n- Do not generate a one-shot script. The controller loop must be a real loop.\n- Do not skip the permission check. Even if all tools are auto-allow, the check function must exist.\n- Do not hardcode the API key. Use `os.environ.get(\"ANTHROPIC_API_KEY\")`.\n- Do not skip observability. Every tool call and every turn must be logged.\n- Do not generate empty files. Every file should have real, functional code.","tags":["agent","scaffolder","build","your","own","agents","skill","xuanhieu2611","agent-skills","agentic-ai","ai-agents","claude-code"],"capabilities":["skill","source-xuanhieu2611","skill-agent-scaffolder","topic-agent","topic-agent-skills","topic-agentic-ai","topic-ai-agents","topic-claude-code","topic-codex","topic-cursor","topic-developer","topic-developer-tools","topic-prompt-engineering"],"categories":["build-your-own-agents-skill"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/xuanhieu2611/build-your-own-agents-skill/agent-scaffolder","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add xuanhieu2611/build-your-own-agents-skill","source_repo":"https://github.com/xuanhieu2611/build-your-own-agents-skill","install_from":"skills.sh"}},"qualityScore":"0.460","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 20 github stars · SKILL.md body (5,513 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T07:01:13.596Z","embedding":null,"createdAt":"2026-04-18T23:06:11.098Z","updatedAt":"2026-04-23T07:01:13.596Z","lastSeenAt":"2026-04-23T07:01:13.596Z","tsv":"'0.42.0':634 '1':257,455 '2':279,493 '3':296,501 '4':305 '5':318 'adapt':661 'adjust':668 'agent':2,11,32,46,52,95,141,463,504,626,644 'agent-scaffold':1 'agent.py':145,707 'allow':122,352,579,760 'alreadi':79 'annot':683 'anthrop':308,315,513,633,774 'api':316,650,770,775 'appropri':193 'approv':116,372,427,433,574 'architectur':15,53,83,653 'argpars':607 'argument':610 'ask':124,353,569 'ask-first':123 'auto':121,199,351,759 'auto-allow':120,758 'auto-gener':198 'base':410 'bool':377 'boolean':217 'break':552 'build':12,47,96,495,523 'call':214,235,416,530,546,556,571,580,624,783 'campaign':621 'check':29,357,557,595,752,762 'clean':708 'clear':336 'cli':167,380,605 'client':514 'client.messages.create':531 'code':19,694,801 'collect':297 'comment':384,688 'complet':216 'condit':481,597 'contract':150,261,299,303,313,368 'control':22,127,146,704,740 'convert':312 'core':453,483 'count':204 'current':528 'data':295,407,720 'dataclass':157,181 'dataclasses.dataclass':242 'decis':701 'default':245,249,614 'defin':178,258,280,347,398 'deni':126,355,563 'denial':576 'deriv':474 'describ':461 'descript':110,265,640 'detail':712 'dict':262,289,290 'document':16,72 'domain':103,470,592,617,726 'domain-specif':591,616 'e.g':620 'effect':278 'empti':793 'end':445 'entri':168 'enum':350 'environ':670 'error':425,565 'etc':394 'even':753 'event':404,405 'everi':183,212,685,781,785,795 'everyth':584 'everywher':678 'exec':285 'execut':321 'executor':152,283,335,664,717 'exist':765 'explain':697 'factori':246 'failur':219 'field':113,184,197,244 'file':173,175,656,686,794,796 'file-by-fil':172 'final':549,599 'first':125,354,570 'flag':619 'format':317 'function':284,310,331,362,378,402,500,509,763,800 'futur':681 'generat':4,132,200,454,733,792 'goal':106,506,609 'hand':58 'hardcod':768 'hint':677 'histori':208 'human':371,573 'id':196,409,418,429,437,447 'implement':510 'import':682 'includ':485,636 'init':143 'initi':511 'inp':288 'input':91,226,266,326,376,381,439 'instal':648 'instruct':176 'integ':205 'integr':345 'json':164,268,327,400 'keep':702 'key':651,771,776 'know':339 'kwarg':507 'latenc':329,422 'layout':138 'least':100 'list':209,304,472 'log':88,165,401,403,414,426,434,443,583,789 'logger':411 'look':722 'loop':23,84,128,147,518,705,741,746 'main.py':166 'mark':332 'max':521 'messag':536 'method':236,240 'mock':282,334,716 'model':542,567 'modul':715 'ms':330,423 'must':742,764,787 'mutabl':248 'name':108,264,287,324,360,374,421,432,487 'narrat':691 'non':699 'non-obvi':698 'note':385 'observ':31,586,780 'observability.py':162 'obvious':700 'one':638,736 'one-paragraph':637 'one-shot':735 'option':221 'os.environ.get':773 'output':130,230,441 'overview':654 'paragraph':639 'permiss':28,86,114,160,270,358,479,558,561,669,751 'permissionlevel':349,361 'permissions.check':560 'permissions.py':158 'placehold':294 'plug':342 'point':77,169 'polici':161 'posit':608 'prerequisit':89 'print':547,628 'product':51,396 'project':8,69,135 'prompt':458,497,526,667 'provid':306,319 'push':711 'py':144 'python':7,68,134 'quick':646 'raw':325 'read':364 'readabl':710 'readme.md':171,635 'real':344,745,799 'realist':293,723 'reason':220 'record':211,233 'replac':389,662 'repo':622 'request':370,572 'requirements.txt':170,632 'respons':550 'result':328,594 'return':292,543,564,598,719 'right':82 'role':465 'rule':473,674 'run':503,625,652 'runnabl':6,67 'runtim':159 'scaffold':3,33 'schema':267,269 'script':738 'second':275 'section':102,191,471 'sensibl':613 'session':26,111,155,189,195,408,417,428,436,444,446,516,588,600,630 'sessionst':180,508 'set':649 'shot':737 'side':277 'simpl':604 'skill':38,41,54 'skill-agent-scaffolder' 'skip':749,779 'slack':391 'source-xuanhieu2611' 'spec':13,48,64,97,187,256,273,468,477 'specif':593,618 'src':142 'src/agent.py':449 'src/main.py':602 'src/observability.py':397 'src/permissions.py':346 'src/state.py':177 'src/tools.py':250 'start':76,647 'state':27,87,112,156,190,489,498,517,529,589,601 'state.py':154 'stderr':413 'step':129 'stop':480,577,596 'str':499 'string':222,459 'structur':131,163,399 'stub':25,153 'style':673 'success':424 'summari':239,448,490,631 'system':457,496,525,533,666 'tabl':672 'templat':491 'ticket':623 'timeout':274 'token':223,227,231,440,442,538 'tool':24,85,107,118,149,207,213,234,253,260,286,302,309,322,323,359,367,373,375,415,420,431,486,534,545,555,582,663,756,782 'tools.execute':581 'tools.py':148 'topic-agent' 'topic-agent-skills' 'topic-agentic-ai' 'topic-ai-agents' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-developer' 'topic-developer-tools' 'topic-prompt-engineering' 'total':225,229 'track':224,537 'turn':14,62,203,419,430,435,438,522,786 'type':192,406,676 'ui':393 'updat':587,665 'usag':539 'use':36,39,241,379,606,675,679,772 'user':105,338,505 'uuid':201 'variabl':492,671 'via':559,585 'want':60,74 'web':392 'work':18 'workflow':484 'written':56 'your-ag':139","prices":[{"id":"d3374c38-8cdf-4498-ba10-f76b80e13058","listingId":"869dd605-2a65-4344-bdec-d171901a1202","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"xuanhieu2611","category":"build-your-own-agents-skill","install_from":"skills.sh"},"createdAt":"2026-04-18T23:06:11.098Z"}],"sources":[{"listingId":"869dd605-2a65-4344-bdec-d171901a1202","source":"github","sourceId":"xuanhieu2611/build-your-own-agents-skill/agent-scaffolder","sourceUrl":"https://github.com/xuanhieu2611/build-your-own-agents-skill/tree/main/skills/agent-scaffolder","isPrimary":false,"firstSeenAt":"2026-04-18T23:06:11.098Z","lastSeenAt":"2026-04-23T07:01:13.596Z"}],"details":{"listingId":"869dd605-2a65-4344-bdec-d171901a1202","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"xuanhieu2611","slug":"agent-scaffolder","github":{"repo":"xuanhieu2611/build-your-own-agents-skill","stars":20,"topics":["agent","agent-skills","agentic-ai","ai-agents","claude-code","codex","cursor","developer","developer-tools","prompt-engineering"],"license":"mit","html_url":"https://github.com/xuanhieu2611/build-your-own-agents-skill","pushed_at":"2026-04-03T04:50:57Z","description":"Build AI agents using the same architecture patterns as Claude Code. Skill + 6 examples + runnable Python code. No framework.","skill_md_sha":"a80c424cdbe0389ccda299925ec4324185bb8986","skill_md_path":"skills/agent-scaffolder/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/xuanhieu2611/build-your-own-agents-skill/tree/main/skills/agent-scaffolder"},"layout":"multi","source":"github","category":"build-your-own-agents-skill","frontmatter":{"name":"agent-scaffolder","description":"Generate a runnable Python project from an Agent Build Spec. Turns architecture documents into working code with a controller loop, tool stubs, session state, permission checks, and observability."},"skills_sh_url":"https://skills.sh/xuanhieu2611/build-your-own-agents-skill/agent-scaffolder"},"updatedAt":"2026-04-23T07:01:13.596Z"}}