Why Skills Fix AI Workflow Pain Points

AI agents like Claude start every conversation from scratch, forcing you to reload context, conventions, and instructions repeatedly. This wastes tokens and time, especially across multiple repos or team members. Memory files like .claude.md or .agents.md help by appending global or repo-specific rules (e.g., "use pnpm and Vite here"), but they bloat context windows, apply indiscriminately, and lack determinism—no built-in script execution means non-deterministic outputs vary by model, thinking level, or tab.

Skills address this as discrete, composable units: small-footprint folders encoding exactly what matters for a task. They're portable (share across codebases), focused (loaded only when relevant), and deterministic (via scripts). A 30-line markdown file can transform generic repo analysis ("looks pretty good") into hyper-specific feedback ("README drift violates our semantic commit policy; routing uses Next.js conventions").

Quote: "it's almost like carrying if you will the dry pattern into the agentic era in a way um and not repeating yourself" — on skills enabling Don't Repeat Yourself for agents.

Anatomy of a Skill: Frontmatter Drives Routing

A skill is a folder named after the skill (e.g., repo-roast), containing skill.md with YAML frontmatter:

---
name: Repo Roast
description: Analyze and roast a git repo for code quality, conventions, and issues using team-specific constraints.
---

• Name: Human-readable label.
• Description: Critical routing mechanism—LLMs scan it at runtime to decide relevance. Write for AI, not humans: e.g., "User wants fun, critical repo analysis checking stale todos, commit hygiene, and our Vite/pnpm stack." Test by asking Claude: "When would you load this skill?"

Follow with constraints (more effective than prescriptions):

• "Never vague; cite code with line numbers and git commits."
• "Flag README drift, semantic commits only."
• "In this repo: Vite, pnpm—no npm/yarn."

Add context (images, refs) or scripts for determinism. Skills aren't just markdown—they're folders with anything: scripts, data files.

Common Mistake: Over-prescription bloats like a novel; constraints guide creativity. E.g., "Never skip steps" > "Do step1, step2 exactly."

Quote: "the description is incredibly powerful and loaded this is what the LLM is going to use at runtime to essentially do routing and determine if this skill is relevant"

Adding Determinism with Script Interpolation

Inject real data via Claude-specific ! + backticks for execution:

Stale todos: `!git grep -l "TODO\|FIXME" -- *.ts *.js | xargs cat`
Latest commits: `!git log --oneline -10`

Claude interpolates outputs directly (like JS ${}), piping commands (e.g., git log | awk '{print $1}'). This saves tokens, ensures consistency—no hallucinated git history. Ideal for status reports, metrics.

Before/After:

• Without: AI speculates "latest commits," varies across runs.
• With: Deterministic list feeds reasoning, repeatable.

Extend to any bash: grep stale todos, npm audit, coverage stats. Non-slurping (no keys needed for local git).

Principle: Formalize workflow pieces once; skills bootstrap non-deterministic convos with facts.

Loading, Sharing, and Iteration Loop

Placement:

Dev loop: Edit → Save → Invoke ("roast this repo") → Critique → Repeat. Use Claude's built-in skill builder skill: "Critique this skill.md," "Evaluate output," "Suggest description improvements."

Skills compose: One calls another (Claude can, but sparingly). Non-technical users share via Claude Desktop (connectors to Slack/Notion).

Quote: "Claude ships with a fantastic uh skill builder skill or skill creator skill and uh that is really good for critiquing your skill setting it up in a way that Claude would expect it to be uh and even evaluating it"

Hands-On: Building Repo Roast Skill

Assumed Level: Comfortable with Claude/Cursor, git basics. Fits after basic prompting, before agent orchestration.

Steps (from workshop repo clone via QR):

1. Frontmatter: Name/describe for routing ("roast repo" triggers).
2. Constraints: List 3-5 (no vague, cite lines/commits, stack-specific).
3. Scripts: Interpolate git commands (todos, commits, deps).
4. Test: Claude → Output → Refine desc/constraints.
5. Share: share.sh uploads to KV; presenters demo live.

Quality Criteria: Repeatable format, comprehensive yet concise, fun/engaging. Good: Specific, actionable roasts. Bad: Generic, misses constraints.

Customization: Inject team rules (e.g., "ESLint violations = fire"). Vary seriousness/creativity.

Exercise: Build baseline, tweak for your stack, share variants. Discuss: Skills vs. .claude.md? (Skills for tasks; md for always-on rules—minimize md bloat).

Quote: "provide just three constraints and say never be vague or um when you site code it always has to have a specific line and a git commit reference with it um then you'll get better performance"

Scaling Skills Across Teams and Tools

Solo: 12 agents with tailored skills. Teams: Uniform execution (recruiting skill pulls Slack/Notion for reports). Portable: No repo-pull dependency.

Composable: Image gen skills route by domain (pixel art for blog; S3 for work). Agents.mmd standardization pending, but Claude/Cursor/Copilot/Desktop universal.

Trade-offs: Claude-dominant (91% room); Pi hacks extensions. Scripts local-only (git, no remote keys).

Quote: "as soon as you gave them that skill then everyone on the team is running it in a uniform way"

Key Takeaways

• Start skills with precise description for AI routing: Test by asking "When to use?"
• Favor 3-5 constraints over step-by-step: Guides without bloating.
• Use `!`` script interp for determinism: Git logs, todos—feed facts to LLM.
• Place repo-local for projects, global for cross-use; symlink for multi-tools.
• Iterate with Claude's skill builder: Critique, evaluate, refine.
• Share via folders/KV: Team uniformity without context reload.
• Skills > memory files: Task-focused, portable, composable.
• Minimum viable: 30-line md yields hyper-specific outputs.
• Ask LLM meta-questions: "Skills call skills?"—leverages self-awareness.