brycewang-stanford/skill-development

Skill Development

Use this skill to create or repair Claude skills in the current local environment, not in an abstract plugin template.

Goal

Produce a skill that is:

• easy to trigger,
• lean at the SKILL.md layer,
• backed by real references/, examples/, and scripts/ files when they are mentioned,
• free of dead local references.

Core rules

• Keep one skill = one durable job.
• Treat the frontmatter description as the main trigger surface.
• Keep SKILL.md focused on workflow and boundaries.
• Move detailed catalogs, templates, and long explanations into references/ or examples/.
• Do not mention files that do not exist.
• Do not inherit stale names, agents, or sibling skill references without verifying they exist locally.

Default workflow

1. Inspect the current environment first

Before writing anything:

• inspect the target skill directory,
• inspect neighboring skills that already solve a similar problem,
• verify which agents, commands, and sibling skills actually exist,
• identify stale references before adding new ones.

Use the local inventory as the authority. Do not write guidance against an imagined plugin layout.

2. Lock the skill contract

Define four things before editing:

1. what the skill does,
2. what triggers it,
3. what it explicitly does not do,
4. which bundled resources are actually needed.

If the skill only needs a short workflow, keep it short. Do not create references/, examples/, or scripts/ just because the directories are conventional.

3. Write or repair the frontmatter

The frontmatter should:

• use the real skill identifier in name,
• use a third-person trigger description,
• include concrete phrases a user would naturally say,
• stay short enough to scan quickly.

Prefer descriptions of this form:

---
name: skill-name
description: This skill should be used when the user asks to "...", "...", or needs help with ....
---

4. Keep the main file lean

A good SKILL.md should usually contain:

• a short goal section,
• role boundaries,
• a default workflow,
• safety or quality rules,
• a short list of additional resources.

Move these out of the main file when they get long:

• templates,
• exhaustive checklists,
• edge-case catalogs,
• sample outputs,
• long examples.

5. Add only real bundled resources

Use bundled resources deliberately:

• references/ for detailed guidance that may be loaded selectively,
• examples/ for real example outputs or scaffolds,
• scripts/ for deterministic helper logic.

If a resource is mentioned in SKILL.md, it must exist. If a resource exists but is never referenced or used, delete it.

6. Run integrity checks before closing

At minimum, verify:

• frontmatter parses,
• referenced local files exist,
• sibling skill or agent references are real,
• SKILL.md is not overloaded with material that belongs in references,
• temporary logs, caches, and editor artifacts are not left inside the skill directory.

Typical repair patterns

When the skill is too long

• keep the trigger and workflow in SKILL.md,
• move catalogs and deep detail into references/,
• keep a short read order so another model knows what to load first.

When the skill is too thin

• add a default workflow,
• add at least one concrete example or checklist,
• make the boundaries explicit so the skill is not just a slogan.

When the skill has stale references

• remove dead paths immediately,
• replace historical names with current local names,
• re-check neighboring agents/commands/skills against the live directory.

Recommended output shape

When creating or repairing a skill, prefer ending with:

• what changed,
• which files were created or updated,
• what integrity checks were run,
• what still needs manual follow-up, if anything.

References

Load only what is needed:

• references/checklist.md - compact quality checklist before closing a skill edit
• references/integrity-checks.md - concrete local checks for missing files, dead references, and drift
• references/skill-creator-original.md - legacy background reference; use for context, not as the live source of truth