Lesson 2 - Designing a Skill Artifact

Here's the complete anatomy of a skill: ``` deploy-checklist/ # Folder name = skill name (kebab-case) ├── SKILL.md # Required — frontmatter + instructions ├── references/ # Optional — templates, examples, style guides │ ├── template.md │ └── example-good.md ├── scripts/ # Optional — automation scripts │ └── run-sanity-check.sh └── assets/ # Optional — data files, configs, images └── release-matrix.json ``` **Only SKILL.md is required.** Everything else is optional. Start minimal, add directories when you need them.

Here is the running example skill we'll build across this course: ```markdown --- name: deploy-checklist description: Run pre-deploy validations before shipping backend services to production. Checks migrations, tests, environment variables, and team notifications. --- # Deploy Checklist ## Trigger Activate when the user is about to deploy backend services to production or staging. Do NOT activate for frontend-only changes or documentation updates. ## Workflow 1. Check for pending database migrations — list any unapplied migrations. 2. Run the test suite — report pass/fail with summary. 3. Verify environment variables — confirm all required vars are set for the target environment. 4. Check for uncommitted changes — warn if the working directory is dirty. 5. Generate a deployment summary for the team notification. ## Constraints - Never run destructive commands (DROP, DELETE, rm -rf) during validation. - Do not proceed if tests fail — stop and report the failures. - Do not modify any source files — this skill only validates and reports. ## Output Return a markdown checklist: ### Deploy Readiness Report - [ ] Migrations: [status] - [ ] Tests: [pass/fail count] - [ ] Env vars: [status] - [ ] Clean working directory: [yes/no] - [ ] Summary: [one-line description of what's being deployed] ``` This is a complete, working skill. We'll refine it over the next five lessons.

**Required fields (open standard):** | Field | Rules | Example | |-------|-------|---------| | `name` | Lowercase + hyphens, max 64 chars, must match folder name | `deploy-checklist` | | `description` | Max 1024 chars, explains WHEN to use the skill | `Run pre-deploy validations before shipping backend services` | **Optional fields (open standard):** | Field | Purpose | Example | |-------|---------|--------| | `license` | License for sharing | `MIT` | | `compatibility` | Platforms tested + requirements | `Tested on Claude Code, Copilot` | | `metadata` | Arbitrary key-value pairs | `author: Jane Doe` | **Note:** Some platforms add extra fields (Lesson 6 covers these). Always use the standard fields first.

Your AI doesn't read every skill fully at startup — that would be slow. Instead, it uses **three-stage loading**: **Stage 1 — Metadata (~100 tokens):** At startup, the AI reads only `name` and `description` from frontmatter. This is how it knows what skills exist. **Stage 2 — Instructions (<5,000 tokens):** When a task matches a skill's description, the AI loads the full SKILL.md body. Now it has detailed instructions. **Stage 3 — Resources (on demand):** Only when referenced by the instructions, the AI reads files from `scripts/`, `references/`, or `assets/`. This is why a great `description` matters so much — it's the gateway to everything else.

Ask these questions before adding a directory: | Question | If Yes → | Example | |----------|---------|--------| | Am I pasting the same template into SKILL.md? | Move it to `references/` | Output template, style guide | | Do I need repeatable automation? | Create a `scripts/` file | Lint checker, test runner | | Does the AI need static data to do its job? | Store it in `assets/` | JSON config, CSV data | | Is SKILL.md over 400 lines? | Split content into supporting files | Long examples → references/ | **Default answer: not yet.** Start with just SKILL.md. Add directories when you feel the pain.