If you’ve been working with AI coding agents for a while, you’ve probably started collecting workflows. You might not call them that yet, but they’re there. Another name for workflows is Skills.

Some are tiny: run these checks before shipping. Some are project-specific: when you touch this library, preserve this API contract. Some are operational: never print secrets, always summarize the logs. Right now they probably live in chat history, a README note, a shell alias, or your own memory. That works until it doesn’t.

A skills repo is a better shape for this. It’s one place to collect, version, review, and share the workflows that make agents useful in your projects. I built my own yesterday, so let me walk through how I think about it.

A skill is judgment, not a command list

The first mistake is treating a skill like a list of commands. Commands matter, but they’re the easy part. The real value is judgment: when to run the command, what to inspect first, what not to do, how to validate the result, and what risks are specific to this tool.

A good skill makes an agent more careful. It narrows the space of bad decisions. So before you write a single instruction, figure out who the skill is for.

Separate adoption from maintenance

Most serious projects have two audiences: people using the project, and people maintaining it. Those should usually be two different skills.

An adoption skill helps an outside developer get value from your project. Install the package, configure it correctly, use the right import path, migrate existing code, avoid the common mistakes, run the right validation.

A maintainer skill helps contributors work inside the source repo. Understand the layout, run the local quality gate, preserve compatibility promises, follow the release conventions.

Here’s why you need two. If you only write maintainer skills, your repo becomes a private automation folder. If you write adoption skills too, it becomes onboarding infrastructure.

Keep each skill focused

A skill should have a job. Not “everything about this project.” Not a duplicate README. Good skill names are verbs: integrate, audit, upgrade, migrate, debug, ship. That keeps the trigger obvious, so when someone asks the agent to do that kind of work, the skill has a clear reason to load.

If a project needs multiple workflows, split them. A library might have integrate and develop. A deployment system might have deploy and rollback. Don’t cram them into one file.

Put the safety rules near the top

The most important part of many skills is the “do not” section:

• Do not print secret values.
• Do not delete or archive anything without confirmation.
• Do not add failing CI enforcement unless asked.
• Do not do broad rewrites before previewing a diff.
• Do not commit local registry URLs.

Agents are good at momentum. Safety rules are how you make that momentum usable. The more destructive the workflow, the more explicit the guardrails should be.

Include validation, not just execution

Every skill should answer one question: how do we know this worked? That might be pnpm test && pnpm build, or cargo test && cargo clippy -- -D warnings, or go test ./.... For non-code workflows it might be “export the review list” or “verify the generated config is ignored by git.”

This matters because agents can complete every step without completing the work. Validation closes the loop.

Write for the agent inside the repo

Skills should assume the agent is operating in a real project with real files and existing conventions. So the useful instructions look like:

• Inspect package.json before choosing a package manager.
• Read the existing test scripts before adding new ones.
• Prefer the local task-runner commands when they exist.
• Check the framework boundary before picking an import path.

That’s the context generic model knowledge won’t reliably infer. And it’s why you shouldn’t just copy the README into the skill. A README is for a human browsing the project. A skill is for an agent doing work. They overlap, but they aren’t the same artifact. Keep the skill short enough that loading it is cheap.

Use a marketplace repo as the index

Your skills repo doesn’t need to be the canonical home for every skill. Some projects should own their own plugin metadata, especially if they already have a CLI, release process, and docs. Your marketplace can just point at them remotely. Other skills can live directly in the marketplace repo. One structure that works:

skills/
  .claude-plugin/
    marketplace.json
  plugins/
    esm/
      .claude-plugin/plugin.json
      skills/develop/SKILL.md
    upkeep-rs/
      .claude-plugin/plugin.json
      skills/audit/SKILL.md

The marketplace becomes the thing people add once. Individual plugins stay free to live locally or point at their canonical upstream.

Scan third-party skills before you import them

The moment your marketplace points at someone else’s plugin, you’ve inherited their security posture. And skills are a soft target. The dangerous payload usually isn’t code, it’s prose: an attacker buries instructions inside a SKILL.md, gated behind an innocent-sounding trigger, that tell the agent to read your .env and send it somewhere. A normal code scanner walks right past that. There’s no malware signature to match. It’s just English.

This isn’t hypothetical. Snyk’s ToxicSkills research found prompt injection in 36% of the skills they tested, across more than a thousand malicious payloads. If you’re pulling skills from a public index, some fraction of them are trying to do something you didn’t ask for.

So run a scanner before you add anything you didn’t write. A few worth knowing:

• Snyk agent-scan inventories your installed agents, MCP servers, and skills, then checks them for prompt injection and data-handling problems.
• NVIDIA SkillSpector scans repos, URLs, or single files against a big catalog of patterns: injection, exfiltration, privilege escalation, tool poisoning.
• claude-skill-antivirus is purpose-built for Claude Code skills and runs several detection engines at once.

One caveat worth internalizing: scanning an MCP config can execute it, because starting a stdio server means running the command in the file. Do that in a sandbox, a container or a throwaway VM, not on your main machine. The tool you run to check for danger shouldn’t be the thing that sets it off.

This cuts both ways. If you publish a plugin others will install, a clear “do not” block and an honest description of what the skill touches is part of being a good citizen of the marketplace.

Start with your serious projects

You don’t need a skill for everything. Start where better agent behavior would matter: public libraries people might adopt, CLIs with safety-sensitive workflows, tools with tricky setup, projects with recurring maintenance, systems where mistakes are expensive.

For each one, ask yourself:

• Who is this for: user, maintainer, operator, contributor?
• What’s the concrete task?
• What should the agent inspect first?
• What commands are preferred, and which are dangerous?
• What should never happen silently?
• What validation proves the work succeeded?

Answer those and you have enough to write a useful first skill.

Why it’s worth doing

A skills repo turns scattered project knowledge into reusable operational guidance. But it also forces a better product question. If this project is meant to help people, what would it look like for an AI agent to help them use it well?

That’s a higher bar than “can the agent run the command?” The point isn’t to automate everything. It’s to package the judgment around your tools so the next agent starts from a better place.

I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].