Write Skill

Understand Requirements First

When asked to create or edit a skill:

1. If helpful, ask clarifying questions about the skill's purpose:

   • What specific problem does this skill solve?
   • What should the output/outcome be?
   • What context or inputs will the skill work with?
   • What are the key behaviors or patterns it should enforce?

2. Summarize your understanding and get user confirmation:

   • "Let me confirm: this skill should [summary]. Is this correct?"
   • Wait for user approval before proceeding

You cannot create a good skill without understanding what you're building.

New Plugins

A skill in a new plugin stays invisible until the plugin is registered and enabled, so land that first, as its own commit, before writing the skill:

1. Add plugins/<plugin>/.claude-plugin/plugin.json and the plugin's entry in the repository's root .claude-plugin/marketplace.json.
2. Enable it in both Claude Code settings files, ~/.dotfiles/tag-personal/claude/settings.json and ~/.dotfiles/tag-work/claude/settings.json, as "<plugin>@landonschropp": true. Missing one leaves the plugin working on only half the machines.

The dotfiles are a separate repository, so that step lands there. Claude Code reads the setting at startup, so the new skill only appears in sessions opened afterwards.

Testing

After writing a skill, ask the user: "Would you like me to test the skill?" (Skills are often manually tested by the user, or can't be tested in an automated way, so you should ask before proceeding.)

If the user opts for the agent to test the skill:

1. Design a scenario that exercises the skill's core purpose. Describe it to the user and get approval before running it.
2. Run the scenario with a subagent. Document exactly what the agent did—what choices it made, what worked, what didn't.
3. If the agent failed or rationalized away the skill's intent, identify the gap, add an explicit counter to the skill, and re-test.
4. Repeat until the skill reliably produces the intended behavior.

Scripts

When a skill includes executable scripts, REQUIRED: Use the ls-scripting:script skill for language selection and conventions.

Interactive File Editing

If a skill needs the user to edit a file mid-workflow and hand the result back, add to its SKILL.md: REQUIRED: Invoke the ls-interactivity:interactive-edit skill.

Required Reading

STOP. Read these documents NOW. Not later. Not "as you go." Right now.

• Format Guide
• Getting Agents to Follow Instructions
• Agent Skills
• Skill Specification
• Skill Authoring Best Practices
• Persuasion Principles