Practical guides
Step-by-step workflows, reusable briefs, and agent guardrails
Design, Chunk, and Blind-Test Agent Skills Like a Product
Turn recurring workflows into durable engineering assets with SKILL.md, silent post-check onboarding, deterministic scripts, per-page chunking, and blind A/B evaluation.
Package this workflow as a project-scoped Skill: 1) define triggers, inputs, outputs, and exclusions in SKILL.md, instructing agents to invoke scripts/ directly without reading their source; 2) put deterministic transforms and post-checks in scripts, writing one intermediate file per page before bundling; 3) spawn a fresh sub-agent to run a blind A/B evaluation comparing outputs with and without the Skill.
Avoid polluting global context with dozens of domain Skills. Create a concise AGENTS.md mapping project purpose and key files, store domain Skills inside the project directory, and write unambiguous trigger descriptions in SKILL.md.
- Explicitly instruct in SKILL.md: 'Do not read scripts/ source; invoke the CLI directly'
- Use safe defaults automatically and print a one-line customization hint at the end of stdout
- Move all deterministic transformations (FFmpeg cuts, HTML bundling, geometry checks) into scripts
What to keepA fresh session reads AGENTS.md automatically and triggers the right project Skill without colliding with unrelated global tools.
Move timestamp math, file merging, and schema checks into deterministic scripts/ while keeping semantic judgment in the Agent. Never make the Agent read script source code just to check config—run with defaults first and print a short customization hint at the end.
What to keepFirst-time invocation succeeds with zero setup and minimal token overhead.
Prevent lightweight models from truncating long outputs by writing one page or stage per intermediate file before script bundling. For visual covers, layouts, or captions, inject results into a local HTML preview page for fast human confirmation.
- Compare 'with Skill' vs. 'without Skill' outputs using a fresh blind reviewer sub-agent
- Verify cross-platform path handling without hardcoded local paths
- Keep domain Skills inside the project directory and index them in a concise AGENTS.md
What to keepLong documents or multi-slide decks retain all source facts and can be reviewed visually in a local browser tab.
Run the same real task with and without the Skill, then pass both anonymized outputs to a fresh sub-agent to grade completeness, rule adherence, and token cost; verify path handling across macOS and Windows.
What to keepBlind evaluation logs show the Skill version consistently outperforms the baseline prompt.