Jimmy Beckett's Skill Explanation
https://github.com/j-r-beckett/SpeedReader/blob/main/.claude/skills/skill-creator/SKILL.md
Don't rely on users saying magic words. Think about what situations call for this skill, including ones where Claude should decide to use it on its own, then write a description that captures those scenarios.
Note that the description must be 1024 characters or less, and it must be on a single line (Claude Code does not support multiline YAML).
I'm not sure exactly how much I agree with this:
For scripting, always prefer python. Run shell commands with
subprocess.run. Don't use shell commands for operations that could be performed in python (file manipulation, hashing, regex, etc). When done properly, these scripts are trivially portable across platforms.
Personally, I'd follow this to the letter because one of my first languages was Python and I'm a big fan of Python acting as scripting and tooling. I agree that Python is super portable and is a winget away these days if you're on Windows, but there are people who are vehemently against Python. I'd check the vibe at your workplace/team before committing to this, but I think the general idea is very good: use some sort of popular scripting language that's amenable to your coworkers/team.
Design the API of scripts with care. Always provide
--help. Avoid exposing unneeded configuration parameters. Scripts should create clean abstractions for Claude to consume. As Claude works, contents of SKILL.md will fade but the script's API will remain, so make sure it's good.
This is huge: context windows shrink but a script's --help command will always be there and something the agent uses naturally.
Read the three principles Jimmy provides!
Big fan of Jimmy's approach to building out skills, I did this myself: you build out the skill happy path first and have it do its thing as a test, then you see what kinds of mistakes the agent makes and plug the gaps yourself with "do not"s. You don't try to cut the agent off at the pass by anticipating mistakes, you let the agent make the mistakes first and iterate.