Lesson 5 - Power Features: References, Scripts, and Assets

Here's our deploy-checklist skill after adding all three directories: ``` deploy-checklist/ ├── SKILL.md # Instructions (now references supporting files) ├── references/ │ ├── report-template.md # The exact format for the deploy report │ └── example-good.md # A well-formatted example report ├── scripts/ │ └── pre-deploy-check.sh # Validates git state and migrations └── assets/ └── required-env-vars.json # Env vars to verify per environment ``` **Updated SKILL.md workflow (excerpt):** ```markdown ## Workflow 1. Run `scripts/pre-deploy-check.sh` — verify clean git state and no pending migrations. 2. Read `assets/required-env-vars.json` — verify all listed variables are set for the target environment. 3. Run the test suite and capture pass/fail counts. 4. Generate the deploy report following `references/report-template.md` exactly. 5. See `references/example-good.md` for tone and detail level. ``` The skill went from 'tell me what to check' to 'check it for me and report the results.'

Organize references/ for clarity: | File Pattern | Purpose | Example | |-------------|---------|--------| | `template-*.md` | Output structure the AI must follow | `template-report.md` | | `example-good.md` | What great output looks like | A completed deploy report | | `example-bad.md` | What to avoid (anti-patterns) | A sloppy, incomplete report | | `guide-*.md` | Decision guides, style references | `guide-severity-levels.md` | Keep each file focused on ONE thing. When references/ grows beyond 5-6 files, consider whether the skill is trying to do too much.

Keep scripts safe and predictable: ```bash #!/bin/bash # pre-deploy-check.sh # Purpose: Verify clean git state and no pending migrations before deploy # Inputs: None # Outputs: Status report to stdout, exit code 0 (pass) or 1 (fail) set -euo pipefail # Exit on error, undefined vars, pipe failures echo "Checking for uncommitted changes..." if ! git diff --quiet; then echo "FAIL: Uncommitted changes found" exit 1 fi echo "Checking for pending migrations..." # Add your migration check here echo "PASS: All pre-deploy checks passed" exit 0 ``` **Rules:** - Start with a comment: purpose, inputs, outputs. - Use `set -euo pipefail` for safety. - Echo progress so the AI can report what happened. - Exit 0 for success, non-zero for failure. - Never pipe user arguments into destructive commands without validation.

Always use **relative paths** from the skill directory: ```markdown # Good — relative paths Read `references/report-template.md` for the output format. Run `scripts/pre-deploy-check.sh` to validate pre-conditions. Load environment requirements from `assets/required-env-vars.json`. # Bad — absolute paths (break when shared) Read `/Users/jane/templates/report.md` # Bad — external URLs (create dependency on network) Fetch the template from https://example.com/template.md ``` **Why relative paths matter:** - They work on any machine (your teammate's paths are different from yours) - They keep the skill self-contained — everything it needs is in the folder - They work with progressive disclosure — the AI knows exactly where to look

Add this to the bottom of your SKILL.md so humans and AI can discover all files: ```markdown ## Supporting Files | File | Purpose | When to Read | |------|---------|-------------| | references/report-template.md | Output format template | Step 4 of workflow | | references/example-good.md | Tone and detail reference | Step 5 of workflow | | scripts/pre-deploy-check.sh | Git + migration validation | Step 1 of workflow | | assets/required-env-vars.json | Required env vars per environment | Step 2 of workflow | ``` This table doubles as a maintenance checklist — if a file is missing from this table, it's either undocumented or unnecessary.