Skill Crafting

Skill Crafting

Create effective, discoverable skills that work under pressure.

When to Use

Creating:

• "Create a skill for X"
• "Build a skill to handle Y"

From Session History:

• "Create a skill from this session"
• "Turn what we just did into a skill"
• "Can the database setup we did become a skill?"
• "Could we create a skill from this?" (evaluate first)
• "Should this be a skill?" (evaluate first)

Fixing:

• "This skill isn't working"
• "Why isn't this skill triggering?"
• "Skill didn't trigger when it should have"

Analyzing:

• "Analyze my skill for issues"
• "Run skill analysis"
• "Check this skill's quality"
• "Audit all my skills"
• "Check character budget across skills"

Analyzing a Skill

When user asks to analyze a skill:

1. Run scripts first when available for mechanical checks:

``bash python3 scripts/analyze-all.py path/to/skill/ ``

If scripts fail because of environment or tooling issues, state the blocker clearly and continue with manual review.

1. Read the skill files for qualitative review:

• Read SKILL.md
• Read REFERENCES.md (if exists)
• Read directly linked references/, scripts/, or agents/openai.yaml files when they materially affect behavior

1. Provide holistic feedback covering:

• Script results (CSO, structure, tokens) or explicit blocker if scripts could not run
• Does allowed-tools match what the skill needs to do?
• Does the analysis cover the files that actually define the skill's behavior?
• Is the workflow clear and actionable?
• Are references appropriate and sized correctly?
• Missing sections or anti-patterns?

1. Give verdict with prioritized recommendations

Validation Scripts

| Script | Purpose | Usage | |--------|---------|-------| | analyze-all.py | Run all checks | python3 scripts/analyze-all.py path/to/skill/ | | analyze-cso.py | Check CSO compliance | python3 scripts/analyze-cso.py path/to/SKILL.md | | analyze-tokens.py | Count tokens | python3 scripts/analyze-tokens.py path/to/SKILL.md | | analyze-triggers.py | Find missing triggers | python3 scripts/analyze-triggers.py path/to/SKILL.md | | check-char-budget.py | Check 15K limit | python3 scripts/check-char-budget.py path/to/skills/ |

Quick start:

python3 scripts/analyze-all.py ~/.claude/skills/my-skill/
python3 scripts/check-char-budget.py ~/.claude/skills/

Creating from Current Session

When user asks to create a skill from the current session:

1. Reflect on the conversation — you already have full context
2. Assess skill-worthiness using criteria below
3. If worthy: Generate SKILL.md using methodology in this skill
4. If not: Explain why (one-off, too scattered, etc.)

Skill-Worthiness Criteria

| Question | ✅ Extract | ❌ Skip | |----------|-----------|---------| | Will this repeat? | 3+ future uses likely | One-off task | | Non-trivial? | Multi-step coordination | Just "read, edit" | | Domain knowledge? | Captures expertise | Generic actions | | Generalizable? | Works across projects | Project-specific |

Quick Assessment

Before creating, answer:

1. What pattern repeats? (e.g., "set up auth with tests")
2. What would break without the skill? (steps someone might skip)
3. Who else would use this? (just me? team? public?)

If you can't answer these clearly → probably not skill-worthy.

For Evaluative Questions

When user asks "could this be a skill?" or "any reusable patterns?":

1. Review what you did in this session
2. Identify distinct workflow segments (not exploration/debugging)
3. Apply criteria above
4. Recommend yes/no with specific reasoning
5. If partial: suggest which part is worth extracting

Core Principle

Writing skills is TDD for documentation.

1. RED: Test without skill → document failures
2. GREEN: Write skill addressing those failures
3. REFACTOR: Close loopholes, improve discovery

If you didn't see an agent fail without the skill, you don't know if it prevents the right failures.

Skill Types

| Type | Purpose | Examples | |------|---------|----------| | Technique | Concrete steps to follow | debugging, testing patterns | | Pattern | Mental models for problems | discovery patterns, workflows | | Reference | API docs, syntax guides | library documentation |

Structure

Minimal Skill (Single File)

skill-name/
└── SKILL.md

Multi-File Skill

skill-name/
├── SKILL.md              # Overview ( --help`
3. Apply to request

Works for any gh command. Stays current as CLI evolves.

---

> License: MIT > See also: [REFERENCES.md](REFERENCES.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arvindand
• Source: arvindand/agent-skills
• License: MIT
• Homepage: https://arvindand.hashnode.dev/why-i-reach-for-skills-before-mcp

Install and usage instructions live in the source repository linked above.