Project layout and placeholders

The creator writes a new directory, by default azurefoundry_<short>_skills/, next to the source skill in your repository. The skill folder stays where it is; the Dockerfile copies it into the image at build time. That is why every build runs from the repository root.

<repo-root>/
├── skills/report-generator/              # the source skill (unchanged)
│   ├── SKILL.md
│   └── scripts/
└── azurefoundry_report_generator_skills/
    ├── __main__.py                       # entry point: health probe, run_turn, uvicorn
    ├── claude_skills_agent.py            # the SDK core: options, prompt, events, tokens
    ├── claude_skills_agent_executor.py   # shared agent instance + per-context session map
    ├── http_agent_server.py              # transport: /health, /execute, /tasks/{id}/cancel
    ├── Dockerfile
    ├── .dockerignore
    ├── .env.example
    ├── pyproject.toml                    # what the image installs from
    ├── requirements.txt                  # kept in step with pyproject.toml
    ├── README.md
    └── tests/                            # local diagnostics, never shipped in the image
        ├── README.md
        ├── test_run.py
        ├── test_foundry_direct.py
        ├── test_anthropic_sdk_foundry.py
        ├── inspect_foundry_client.py
        └── debug_sdk.py

For the AMC variant, keep claude_skills_agent.py and the build files, skip http_agent_server.py, claude_skills_agent_executor.py, and the HTTP parts of __main__.py, and add app.py. See Serve the agent to AMC with amc_sdk.

What each file does

Simple placeholders

These are plain search-and-replace across every .tpl file. The examples are for a skill whose frontmatter says name: report-generator.

Naming rules

If the derived names get unwieldy, strip filler words from the agent-side identifiers only. {{SKILL_NAME}} always keeps the skill's full name, because the SDK matches it.

Block markers

Block markers are replaced with code rather than a single value. Each sits next to a comment in the template that explains the choice.

A few more markers appear in the templates: {{NONROOT_EXTRA_DIRS}} (extra directories the non-root user must own, in the Dockerfile), {{OUTPUTS_ENV_VAR}} and {{OPTIONAL_OUTPUTS_ENV_VAR}} (the outputs variable's name, in the agent and .env.example), {{OPTIONAL_OUTPUTS_ENV_SETUP}} (pointing that variable at a temp dir in tests/test_run.py), and {{PROMPT_DOCSTRING}} (the _build_prompt() docstring).