Agentic Coding Essentials Week 1: New Skill

This week I started the Code with JV Agentic Coding Essentials course and spent most of it exploring something I'd heard of but never actually used: Claude skills. I read the docs, explored the Superpowers plugin repo to understand how it's skill based workflow works, and ended up using some of what I learned to build my own skill.

What the heck is a skill?

A skill is a how to guide you give Claude so it knows how to do something specific in your project. Instead of explaining from scratch every time, you write it down once and then Claude follows the instructions whenever you need it.

The Superpowers plugin repo is a good example of a skill library designed to teach Claude how to work within a specific software development workflow. A few features that stood out to me in the superpowers workflow were the TDD-driven feature development, sub-agent driven development, and the idea around creating skills as TDD for process documentation. TDD when I was writing the code never felt very fun if I'm honest but getting a group of agents to do it makes sense (they don't get bored do they...?).

Some learnings

Skills are how you automate the repetitive tasks. Any time you find yourself giving Claude the same instructions over and over, that's a signal to write a skill.

The Superpowers repo follows a philosophy I found compelling — creating skills is TDD for process documentation. Essentially, you run a scenario without the skill first to see what goes wrong, write the skill to fix it, refactor to close the loopholes. If you haven't watched an agent fail without the skill, you don't know what it actually needs to say.

There were a few things I learned this week that surprised me too:

Descriptions should only say when to use a skill — not what it does.

If your description summarises the workflow, Claude might follow the description instead of reading the full skill. You accidentally give it a shortcut.

# ❌ Claude reads this and may think it know enough to proceed and skip the skill body
description: Helps create TIL posts by asking reflection questions, drafting structure, and writing three files
 
# ✅ Claude reads this and knows it needs to open the skill to find out what to do
description: Use when the user wants to write a Today I Learned blog post for the portfolio website

Using @file references loads files whether you need them or not.

I'd been using @ syntax to reference other files. Turns out this force-loads the file into context immediately — burning tokens even when it's not needed. Better to just name the skill and let Claude load it if relevant.

Something I built

I copied the writing-skills and test-driven-development skills from the Superpowers repo into my own project. Then asked Claude to help me review them to see if we could make them more efficient. The writing-skills skill was over 600 lines and the agentskills.io spec recommends keeping skills under 500 so I thought this could be optimised. As a result, I moved the testing methodology and deployment checklist out into separate reference docs, getting it down to just over 400. TBC if this was worth the move or not as this reference documentation is not exactly 'conditional' and will be loaded everytime anyway...maybe I could have left it? But I'm a bit of a sucker for organising content into specific files because lots of text makes my brain switch off, plus the docs are pretty explicit about it... so I'm happy with my choice at this stage.

Then I used my writing-skills skill to build my first skill from scratch: a today-i-learned skill that interviews me about what I've learned and turns it into a blog post. Huzzah, this blog post was born. I plan to write a weekly reflection for this course on my website so it made sense to have a go at automating this weekly task. My new skill allows me to transcribe my weekly reflections into a prompt and voila a written post I can review and edit. The final piece in my loop was asking Claude to review the improvements I requested to the output (fix up the tone, keep closer to my transcription of my reflection to maintain authenticity etc) and use these reflections to improve the skill. Here's my prompt for that:

Based on the changes I have made to your output using this skill, what learnings can you use to improve the skill so I have to make less changes next time. Review my updated til-claude-skills.mdx file as part of your reflection

Week 1 done

I finish this week feeling more confident about working with agent skills. They're a neat way to teach Claude the "how we do things here" for your project, so you're not starting from zero every session and can easily dispatch claude to complete a common tried and true process you'd usually do yourself. I say "tried and true" because I believe skills probably work best when you're automating a process you know well. Sure, you can then introduce improvements as you learn from mistakes or outputs of the AI. But the point I'm taking away is to create skills based on tasks I have done myself and I processes I trust, so I can understand the foundation of thw workflow being implemented. Writing skills really feels like a craft in itself, one that borrows a lot more from software engineering than I expected.