Implementation (SSRA) › Skill anatomy: S·S·R·A

Skill anatomy: S·S·R·A

SSRA expands to Skills, Scripts, References, Assets. Those are the four directories of an Agent Skill, and they are the smallest complete unit of authored capability in this platform. Everything larger in the repository skeleton is the same grammar scaled up: a skill is to a use case what the constitution is to a repo. Get the four right and the rest of the file grammar follows.

The four directories

Only SKILL.md is mandatory. The other three exist so that detail lives on the filesystem rather than in the context window, the discipline the published Agent Skills guidance calls progressive disclosure.

Directory	What it holds	When it enters context	What must stay out
SKILL.md the S in Skills	YAML frontmatter (name, which must match the folder name exactly, plus description, and optionally allowed tools) followed by the markdown procedure and output contract for exactly one use case.	Frontmatter is loaded at startup for every installed skill; the body loads only when the description matches the task.	Universal conventions (the constitution owns those), other use cases' logic, credentials, vendor or model names, anything longer than roughly five thousand words.
scripts/ the first S	Executable Python or shell steps the skill invokes: validators, extractors, renderers, format checks. This is where deterministic execution lives.	Never. The agent runs the script and receives only its output; the source code costs zero context tokens.	Judgment, prompts, anything whose correctness cannot be asserted by an exit code.
references/ the R	Heavy documents read selectively: schemas, lookup tables, specifications, house style guides, section definitions.	On demand, one file at a time, only when the running task names it. A skill may ship dozens; a task typically reads one.	Content pasted into SKILL.md instead of referenced, client data, ontology copies (pin the release, never duplicate it).
assets/ the A	Output templates and static files: the deck template, the docx shell, schemas, example outputs, logos.	Read or copied at render time by scripts, not by the model.	Anything with client branding baked in, branding is a plane value stamped into the template, never an edit of it.

Progressive disclosure, in three levels

Level one, metadata, always resident. Name and description for every installed skill sit in context permanently. This is the entire budget most skills ever spend, so the description is the highest-leverage sentence in the file: it is the trigger, and a vague one means the skill never fires or fires on the wrong task.
Level two, the body, on activation. When the description matches, SKILL.md is read into context. Keep it a procedure, not a library.
Level three, bundled resources, on demand. References are read file by file; scripts are executed rather than read. A skill can therefore carry far more knowledge than it could ever fit in a prompt.

The shape on disk

skills/
  ic-memo-section/
    SKILL.md                     frontmatter (name = folder name) + the procedure
    scripts/
      pull_deal_facts.py         deterministic retrieval across the three stores
      validate_sections.py       schema + completeness check, exit code only
      render_deck.py             writes into the template, never authors prose
    references/
      section_definitions.md     what each IC memo section must contain
      data_source_map.md         which store answers which section
      house_style.md             tone, citation format, number formatting
    assets/
      ic_memo_template.pptx      immutable layout; values are injected
      section_schema.json        the contract validate_sections.py enforces

Authoring rules this platform enforces

One skill, one use case. If a skill needs two descriptions to explain when it applies, it is two skills.
The folder name is the identity. The name in frontmatter must match it exactly; a mismatch is a hook failure, not a review comment.
Write descriptions for retrieval, not for humans. Name the trigger conditions and the artifacts by their real names, because the description is matched against the user's task, not read by a person.
Push detail down, never up. The instinct to paste a specification into SKILL.md is the instinct to put it in references/ instead.
If it can be checked, it is a script. Anything with a testable right answer belongs in scripts/ and is invoked, not reasoned about, the determination rule applied at file level.
Templates are assets, values are plane content. A client never gets an edited template; they get the same template stamped with their values.

The wider repository layout that these skill folders sit inside is on the Repository skeleton page; the per-file authoring contract for constitutions, agent definitions, hooks and servers is on the Authoring contract page.

← Stage gates Authoring contract →