Agent Skills: SKILL.md, progressive disclosure, API use

Try 3 questions on this

Pick an answer to see why each option is right or wrong.

1. You are authoring a custom Agent Skill and writing the YAML frontmatter at the top of its SKILL.md file. Your upload keeps failing validation because a mandatory field is missing, and the error names no field in particular. Which approach should you take?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: B is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Add a version beside the name, since validation requires a name and a version in the frontmatter of every skill.Assumes Skills carry a semantic version in frontmatter, as package manifests do. Nothing in the skill format requires one.The answerB.Add a description beside the name, since validation requires a name and a description in the frontmatter of every skill.Every Skill requires a SKILL.md file whose YAML frontmatter supplies name and description. Those two fields are the only required ones, and they are what Claude loads at startup to decide whether the Skill is relevant.Your answerC.Add an entrypoint beside the description, since validation requires a description and an entrypoint in the frontmatter of every skill.Invents an entrypoint declaration. Claude reads SKILL.md itself and follows references from there, so there is nothing to point at.Your answerD.Add an allowed-tools list beside the name, since validation requires a name and that list in the frontmatter of every skill.Assumes the Skill declares its own tool permissions, which belong to the agent or request configuration rather than to the skill file.

   Written from platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

2. You attach six Agent Skills to a request so that the model can handle several document formats. Your team asks how much of the context window those six sets of detailed instructions will consume before any real work begins, and wants that cost kept down. Which approach should you take?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: D is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Attach three of the six and swap the rest in per format, because a skill's instructions are loaded in full at the start of every request.Eager loading of every attached skill is the problem progressive disclosure solves. If all six instruction sets were injected up front, attaching skills speculatively would be prohibitively expensive, so the design loads detail on demand instead.Your answerB.Attach all six and turn on context compaction, because a skill's instructions are loaded in full and are summarized away only once the compaction trigger is passed.Compaction summarizes earlier conversation context when a run approaches a trigger threshold. It operates on message history, not on skill definitions, and does nothing to change how or when a skill's instructions are read.Your answerC.Attach three of the six and inline the rest of them into your own prompt, because a skill's instructions are loaded in full again on each turn of a conversation.Inlining the instructions yourself is the eager-loading cost by hand: the text sits in the prompt on every request whether or not the format it covers ever comes up. Leaving the skill attached keeps it behind its description until it is invoked.The answerD.Attach all six as they are, because a skill's instructions are loaded in full only when it is invoked, behind a short description of what it does.Agent Skills use progressive disclosure: what the model sees up front is a short name and description of each attached skill, and the fuller instructions and any bundled files are read only when the skill is actually invoked.

   Show the full explanation and doc quotes

   Context consumption is therefore proportional to the skills used rather than the skills attached, which is what makes attaching several of them practical.

   Written from platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

3. Your company standardises a set of custom Agent Skills that every team must use. Administrators must be able to manage the canonical copies centrally, all members of a workspace must get them without individual setup, and the Skills are consumed by backend services calling Claude. Which approach should you take?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: C is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Have every member upload the Skills as zip files in their claude.ai settings.claude.ai custom Skills are individual to each user, and claude.ai does not support centralized admin management or org-wide distribution.Your answerB.Commit the Skills to .claude/skills/ in each service's repository.Claude Code Skills are filesystem-based, personal or project-scoped, and separate from both claude.ai and the API.The answerC.Upload the Skills through the Skills API, where they are workspace-wide.Sharing scope differs by surface. Skills uploaded through the Claude API's Skills endpoints are workspace-wide, so all workspace members can access them, which is the surface backend services calling the API use.Your answerD.Publish the Skills to a public repository and have services fetch them.Publishing source does not make a Skill available to the API; custom Skills must be uploaded to the surface that will run them.

   Written from platform.claude.com/docs/en/agents-and-tools/agent-skills/overview