Ask HN: How do you manage skills files?

There was a time when maybe it mattered (last year), but with good repos and good prompts today's agents can find exactly what they need without any skills.

"Skills" as developer macros can be useful, but at most those are things shared with the team (in the repo), not something you download from the internet. If you have so many skills that you feel the need to manage them, that's a code smell.

I feel like downloading a bunch of skills is another one of those useless collections people make purely because they have infinite options. It’s like those collections of thousands of bookmarks you’re never going to click or pirated ebooks you’re never going to read.

It’s trivial to write your own skills with agents. The best way to use them, imo, is to make them when you have repeatable agent workflows, written to your own personal taste, and updated as your workflows change.

Here’s what I have for reference:

- Remove agent-speak from code, docs, and markdown files.

- Ask sequences of questions the way I like to be asked questions. Used instead of the question tool. This is my primary design skill as well.

- How to use jj the way I want my agent to use jj

- Dispatch subagents with 6 different sets of priorities. Those priorities are defined in the skill, so I can always dispatch all 6 of them to write or review code. Includes a template for code reviews

- Manage a local MD issue tracker for personal projects

- Keep them organised in software repos that you install with symlinks for all coding harnesses that you have. Progressive disclosure based on the frontmatter does the rest.

- I make sure they work with AI evals. Think of them like integration tests to prove behaviour. They're useful to optimize your flows. I try to make my skills be mostly a translation between natural language and good small fast tools that they call.

- I change them as a new problem arises. Not just because.

Skills can't be eaten by model capabilities if skills represent a workflow that is custom to my team or my person.

I wrote about a good mental model in the past:

https://alexhans.github.io/posts/series/evals/building-agent...

Second, we share all of our sets of skills in a purpose built registry: https://noriskillsets.dev/ you can use any of our public skillsets from there. If you're on a team you can also sign up to get your own private registry. Makes organization much easier.

Finally, for local development, we use this CLI to manage skills (https://github.com/tilework-tech/nori-skillsets). This is a tool that lets you bundle skills into groups, and then switch between those groups. So for eg if I'm making a slide deck I'll use an admin skillset, and for coding I'll use a swe skillset, and for debugging I'll use a debugging skillset.

We do keep tinkering with our skillsets, but not very much. I don't get the need to adjust things for every model release, doesn't seem necessary for us in practice

For general tasks, the model seems perfectly capable of figuring out things itself, for project or environment specific tasks, I just put that information in the readme or agents.md file.

I make sure they work by understanding every skill, reviewing pull requests, and testing the end product. The result is rarely perfect, so I am constantly tweaking the skills and how I use AI.

[1] https://github.com/gregwebs/skills-sdlc/

The installation is effortless and I don't have to mess with symlinks as I may be working with same codebase on different platforms which would make things.. different.

  codex plugin marketplace add "https://path-to-my-git-repo"
  codex plugin add agent-tools@mycompany

  claude plugin marketplace add "https://path-to-my-git-repo"
  claude plugin install agent-tools@mycompany

Haven't got to these bits yet, but I'm sure they will work as easy as install does.

  claude plugin marketplace update mycompany
  claude plugin update agent-tools@mycompany

Another thing i discovered is less is more (in case of skills as well)., don’t add lots of skills., keep them very handful - I’ve got 9 skills so far (many people have 100s installed from marketplaces and plugins)

To keep me organized, here's the directory structure I use. So I don't have to think about it, I've created a skill for my skill folder that files any new skills in this structure as I add / ablate any that aren't useful.

   - `Discovery/` — Finding docs, searching, information retrieval
   - `Execution/` — Running processes, CI/CD, releases, deployments
   - `Planning/` — Goals, specs, tickets, threat models
   - `Tools/` — Reusable tool integrations (browser, notebooks, CLI creators)
   - `Debugging/` — Debugging, troubleshooting, fixing
   - `Expertise/` — (reserved) Domain-specific deep knowledge

I've been working on a tool (https://dynobox.xyz) that acts as a deterministic integration test / behavioral test layer for some of the skills i've been working on / sharing.

It feels like a full eval suite is a bit heavy handed and really all I care about is if certain files are touched / left alone or if my skill is actually read. The tooling has much more functionality built in if you want to check it out!

For skill files / prompts I share I make sure that I use the cross harness functionality since I use codex but a bunch of my coworkers use claude (and then one using antigravity...)

I maintain all my skill files in a central location (like dotfile management) and have guix home sync it to the skill folders of various harnesses that I'm playing with (codex, pi, antigravity, Claude Code, Deepseek harness, etc). They're set up to be bidirectional links rather than read-only like the default configuration, so I can keep editing them / adding to the corpus from any harness.

This works well for skills since all harnesses expect the same format, but is more annoying for other features.

EDIT: This is actually an example of a potentially useful skill. You might choose to manage your skills slightly differently. All you need to do is write a skill-management skill for your agents to be able to wire things up correctly / access them for edits.

Some other nifty skills/plugins in my experience: render latex equations, cetz diagrams inline, jujutsu, guix, code reviewer, writing feedback.

1. A single Skill finder skill, loaded in the prompt, prevents having to import all the summaries in the prompt the harness would add. Uses git's own search.

2. Private repo, per agent, contains main (production) and draft-<name of skill> branches.

3. Shared repo, like 2, but general access for all group agents.

4. Fallback mode, search the harness for skills using the harness mechanism when a relevant skill cannot be found.

5. Skill audit cron. Identify junk skills / drafts that have never changed / not in any recent sessions history, and categorise monthly for me to decide.

This means it's compatible with existing skill folders, removal of git and the finder skill is non destructive and critically debloats the prompt of skills that aren't used and lazy loads them when needed.

Then, I use this tool:

https://github.com/a1st-dev/aix

to keep my Claude, Codex, and OpenCode in sync with my config.

The major benefits are that my adoption/deletion of skills, rules, hooks, MCP servers, etc. are deliberate, versioned, and shareable.

And since aix allows you to create extensible configs, that aix-config public GitHub repo is my base set of rules, and my internal/employer-specific rules are just a small layer on top of that.

It also makes trying out different subscriptions easy: you define your config in one place (one source of truth), and write to Claude, Codex, Devin, etc. with one command.

i used to be a bit bearish on skills—thinking that llms should just use --help, but i've come around on that. i think skills are a great way to describe higher level workflows that use multiple commands.

https://jdx.dev/posts/2026-09-05-introducing-packslip/

https://github.com/genged/capshelf

Using capshelf I manage my skills across projects. When I start a new project I can just:

$ capshelf add security-review

From the skill repo.

And if I create a new skill I can promote it to the repo so everyone can install it:

$ capshelf promote security-review

It pins the skill content hash so there are no unexpected edits that can break your flow. It also supports MCP configs and agent configs.

> Do you keep improving them over time?

In my global AGENTS.md I have a note to agents to explain any frustrations they had doing a task, and to suggest any skill/tool/AGENTS.md improvements. I am trying to keep AGENTS.md files small but still finding the balance.

Because it's from Microsoft and sounds sufficiently enterprisey probably.

- Explanation: https://www.minid.net/2026/7/14/how-to-automatise-with-ai

- Git source: https://github.com/meerita/monorepo-nextjs-golang-rust-pytho...

Create a standalone prompt to <xyz>

The latest AIs will print out a long prompt with all of the assumptions, tools, and general files it plans to use. Review that, and then run the whole prompt in a new context.

One thing I've had to write as a layer on top of it is a way to assemble agent-specific CLAUDE.md / AGENTS.md from fragments.

For example, I have a little fragment that has all agents respond to me in ordered list format. (Since they often ask a bunch of question all jumbled throughout a response, the ordered list format allows me to respond to those specific questions.) And I also have a growing anti-Claudeism fragment as well.

Then I combine this with project-specific fragments and have it assembled into into a single CLAUDE.md / AGENTS.md. The layer also does a little reporting on the length of the resulting files and notifies me if it ever grows beyond a certain size.

I try to keep my collection of community skills short, usually a few established names (mattpocock, mcollina, trailsofbit). And then I check new releases (or when mattpocock published a youtube video for instance :D)

> keep them organized

For skills I wrote myself, I have my own private github repo. I use skills like /commands most of the time, so I can tell if they work straight away.

For community skills, a package manager really helps. vercel-labs/skills and withastro/rosie are good options. I also built one myself: https://github.com/osrim/ski. It has some cool features like an update command and a security scan.

If you work in a niche or on special problems, this template could be useful.

I have like 3 skills, and so far so good, most of my recent changes have been asking Claude to please stop using metaphors and creative figures of speech that make the documents so much harder to read and understand (maybe it's only annoying to non-native speakers, I don't know)

Be sure to increment unofficial plugin versions when you make edits: codex's auto-update works reasonably well, claude not so much, but when asked, both can fix their own config.

And like others have said, imho the skills that are incanted as macros are much more reliably useful. I use my technical project plan skill suite in 90% of my sessions via direct reference, and the stage -> cross-model second-opinion review is how I land all my commits.

Maybe better to periodically prune: tweak some skills, shorten some, delete some.

We have a bootstrap script to deploy company-managed skills to each developer's "personal" skills. Hooks for codex and claude code try to refresh the skills on each startup.

I have a configuration file of marketplaces and other skills to fetch, it can look like. I have my own marketplaces as well, including ones from my company. I use vercel's tool for managing skills with npx, but to easily handle specifically _which_ skills to fetch, the config file is set up as follows:

  SOURCES = {
    'some-marketplace-name': [
        'some-skill',
        'another-skill',
        'yet-another',
    ],
    'https://designsystem.yourcompany.com': [], (empty list: fetch all skills)
  }

https://github.com/Tencent/teamai-cli

It's the best thing I've come across (that I don't need to mange myself) https://github.com/p3bot/start

The tool itself does more than just manage skills/prompts but I found that part of it particularly good (well new to me; not familiar with cue but the idea seems like a good fit)

You can have your own skill repository with Skillshare and sync across agents (symlinks or copys).

The first dimension is easy: I simply keep copies of debugged skill files in iCloud and copy them where I need them.

The second dimension is where I spend my time: I use short skill files for fast inference APIs and tiny skill files when I am running slow local models, and I simply spend a lot of time writing and tuning tiny skills files.

Of course, with increasingly better models, skill files become less relevant, but not totally irrelevant.

And sometimes it doesn't follow the instructions well. I have a skill for that too: it tells the agent, given what it knows about attention and LLM:s in general, to evaluate the instructions and the mistake the LLM made, try to diagnose why it didn't follow the instructions as expected, and come up with an improvement of the skill based on that diagnosis.

Source at navikt/copilot

For evals I use the method outlined in the `skill-creator` skill from Anthropic.

In the skills, I try to use scripts, along with templates and json worksheets, as much as possible to scaffold and validate the work to make things more consistent and reliable.

full disclosure: I'm the author

For instance… how to deploy a service or new service’a docker container. Get secrets in value blind, manage secrets value blind. Those sorts of things have been wildly valuable. Also due to the nature of skills and how they are pulled in by your harness they can really prime the context in a way that is really useful to agent autonomy if that is your thing.

There is a rule to always use this skill and then track notes in a version file. Then back it up in a share folder or external drive.

Skills have made my tools immensely better, cheaper to use and faster. I've also added to it that it should write scripts it can just use in the future to do tasks like query information it needs to answer questions.

I wish there was a better way to share these over a team but I haven't taken that time yet.

E.g. https://github.com/eliask/lawvm/blob/master/AGENTS.md

EDIT: Ah, but what I do instead is I constantly refer to my various public essays. I think it's very useful to have externalized thinking like that available for use with LLM contexts.

I tried to control the execution of tasks performed by each project using claude.md within the project, but claude.md is only read at the beginning of each session, so it felt like the instructions weren’t being properly reflected.

So I revised the strategy to manage frequently used features in skill units. In doing so, instead of organizing skills by project, it was structured to be integrated into the general skills of the individual repo.

When skills are spread out across multiple projects and the number increases, it becomes impossible to keep track of which skills are available, so they end up not being used.

I also think that eventually, once Claude(model) advances, it will be able to replace most of the skills, so I believe registering and managing countless skills actually degrades performance.

a model capability is never going to fill in an unknowable blank that a custom skill (or whatever equivalent your paradigm supports) can.

a model might have the cleverness to whoami and look through the .ssh folder for keys and evidence of past connections when asked to connect to bob, but a skills file can just easily say "We connect to bob using key Z and user X." so that the operation gets done without all this nonsense needless inference as far into the future as the information is valid for.

a concise information dense skill is going to always dominate on tokens-burnt for any given task that requires insider knowledge. it simply gets rid of the entire investigative phase of work.

https://github.com/asteroid-belt/skulto

Caveat: It works for Claude Code and Codex, but does not work for Claude Desktop.

https://asmat.ca/blog/mad-skills/

You also need to manage the authority of each skill too. Signed skills is a step in the right direction, but it only proves provenance and doesn't prove behavior.

(Related: https://news.ycombinator.com/item?id=49597166)

I ideally want to have a single place I store my skills with an easy way to make them available to my repos, Amp and ChatGPT desktop/iOS, Grok web but can’t see a way

https://agent-plugins.org/

All skills, MCPs, CLIs, etc. live inside of it. I have it symlinked to all my dev machines so that it doesn't have to be an MCP.

`capsule` is then progressive to dozens of skills/tools thru `capsule` -- ex. `$capsule plannotator [args]`.

In some harnesses, I make it human-invoke only, and call it directly. In others, I let the model invoke it, and it has a top-level description that hints at what's inside.

Maximal context/session start control and capability extension.

I keep most of my sessions in Zed (you can import them there anyway). After some big feature I let a frontier agent go over these sessions and suggest improvements. Typically I use gemini for this because it's really good at pruning text. Claude/GPT really wants to append more text for some reason.

I end up with smaller skills but more "actioned" skills. They kind of force the agent to do things the way that works well.

Everything is organised into repos, i select the directories with the context the agent needs for the task. If I want it to adjust something in my homelab, I drop it into the homelab repo. Stuff agents need to do commonly has shell scripts to speed it up.

I do however have some system prompts. I pick the prompt based on the goal, whether I want to implement something, or just web search, or just need a short one-off command to be done.

I don't need to manage skills files because I have so few of them and they're only a couple lines long.

They get pinned with nix together with the software that they come from.

It's just two 3rd party skills now:

playwright-cli and herdr.

All the rest are skills for the software itself, so they live in the same repo and get updated the same way docs get updated.

I built Skill Grill, an open-source directory and community trust layer for AI agent skills.

Its live now at https://skillgrill.dev

I'm not sure about posting links in threads but this project needs community backing in order to work and its free :)

Its still in MVP stage, but feedback is welcome

https://github.com/boraoztunc/skills

I allowlist one going over our issue management system, and a few around internal processes I believe have value (basically very short pointers at OpenAPI specs for making HTTP reqs - could probably be in the repo AGENTS.md but w/e).

When opening a new repo I'll look if any skills look like they actually give helpful context and aren't Claude vomiting out a torrent of text (over)fitting some insanely specific use case and allowlist those.

Or give up after too much exposure to vile AI created text.

For me, it's like a dev script basically and gets that level of care. I don't need an eval... I'm the only user and I use it like 5 times a day.

1. Personally - these are for apps I use like Codex. This one is pretty simple

2. For our product (which is mostly an internal tool, with minimial customer facing UI) - we have a skills factory that lets our employees create reusable instructions for our internal agent (fully custom built harness with routing). User describes the task and writes the instructions (can attach reference files, etc.). Custom skills and their versions are stored in postgres, with attachments in file storage. The assistant loads those instructions and references when it uses the skill. To update a shared skill, users edit a draft, test it, and submit it for review. Once approved, that version becomes live. Skills can learn or rewrite themselves from conversations (cuts a new draft and prompts the user if they want to update/improve the skill).

EDIT: I should say that our employees have a particular set of expertise and knowledge that make skill sharing insanely useful. Which is why I took the time to build this out. It's helped reduce manual work, and has increased our AI usage drastically. We also measure AI output (in terms of quality) and the reduction in slop has sky rocketed.

No need to over complicate it. Write down things you feel like re-using. Like how to specifically implement something in your system ("when adding a new API endpoint we need to do x y and z", or "when making a github PR we tag Æ and Å") so you don't have to repeat it. And I mostly add it in cases where it didn't infer it itself. So very reactive, not proactive.

Most public skills are useless and over complicated. Lots of people are spending too much time on their harness, than actually making stuff.

Edit: but do get inspired by public ones. For instance a "grill me" skill can ve be useful, but I find the public one very mumbo-jumbo. But the idea of forcing the agent to ask clarifying questions is good.

i then A/B test skills for terseness with weco’s auto-research within this using a much weaker model e.g. Qwen 3.5 4B

I only want the model to have the tools it needs to get the job I ask of it done.

It makes as much sense as the so-called “humanizer” tools that purport to make LLMs stop using their well-known verbal tells.

All you are doing is saying: “Hey you know that thing you can’t stop doing? Can you stop doing that?” The machine will say “Absolutely!” but eventually start doing it again.

All of my skills are custom to my workflows except Contextify (more on that at the end) This extends to how I distribute them across multiple development machines.

They live in my `cli-ai-setup` repo alongside agent settings, git worktree tooling, iTerm workspace restoration (important, machines have to restart and crash sometimes), code review scripts, and machine setup guides. I use git to carry changes between machines and a setup script to symlink the skills into a shared directory that Claude Code and Codex both use.

I have a `skills-and-settings` skill specifically for deciding where new skills belong and how to make them available (project, global, application). I also have a custom `skill-create` skill that turns sessios into new skills or updates existing ones.

Importantly, I also have entire custom applications I have not yet made open source that my cli-ai-stack relies on. I do expect to distribute these so they live in their own repo and are symlinked or installed in as appropriate.

For maintenance, I've largely handled this manually and organically. When a skill is not performing, I'll use the context of the situation as the ~1 shot or pull in more examples for the ai:

   This skill seems to not be performing as expected on [something]. 
   
   This has happened a couple of times now use /total-recall to find similar recent situations for example [something I remember]"

   Recommend updates to the skill and upon approval commit and push them...etc.

This past week I was exploring the automatic skill improvement behavior described in the Anthropic blog guest post with their partner org. I'd previously build a "dreaming" skill that works okay and think there may be some value yet to plumb there.

For skill creation, I have a skill that reads the official skill docs for both Claude Code and Codex. This way the skills are built to handle both platforms particularities. I automatically pull those docs into local Markdown daily, so it has a regularly refreshed reference for what each tool supports.

As mentioned above, I have built Contextify (https://contextify.sh) which provides a sql database of all of my Claude Code an Codex session transcripts across all of my development machines. The skill for this (/total-recall) is the most important skill I have and I use it constantly.

  - start with zero skills

  - add a skill if you encounter behavior that you want to ward against or if 
    you want to associate a meaningful phrase with a certain method of doing things 

  - NEVER copy a skill from someone, do not clone skills repos, do not let LLMs
    write their own skills

  - occasionally revise or delete a skill, less is more

This largely works with a specific model, specific harness, specific prompt, specific context. You may need to modify your agent harness to manage skills depending on runtime parameters. Pi is a great general purpose agent for the these modifications.

If you do find other skills and want to use them, put them through the loop above. But keep in mind that since they were created in their own circumstances, they may not work in yours.

Also separate rules from skills. Rules tell AI when to do things, skills tell AI how to do things. Tool call/MCP limitations, agent configurations, and harness extensions, can help it stay on track.

Making sure they actually work? Trial and error, mostly. I know some folks have tried auto-researcher approaches, but I haven't found that to be the best use of time in my work.

it has all the skills/docs my particular application needs

i treat it as ADRs as it helps the AI understand the parts of the system it is working on

I'm seeing the agent working quite fine with just direct prompting and the agent doing things by itself rather than using skills. Is it better for certain task size?

95% rm

https://mininote.ink/docs/mcp-docs

Agent can use mcp to update its own skills, or I can copy template skills into local dorectories via the api. Very useful, like notion on steroids but is completely free.

You wrote some bullet points so your agent harness doesn't keep making builds in the wrong environment? You have a very specific debugging setup? Your agent doesn't understand when to rebase?

README is where you should be writing anything specific to your project, and if you're worried about context size then your README is too long, it should be just enough information for any competent dev or agent to get the gist of how you do things around here and where to look for deeper answers.

If your particular harness / orchestrator is just not pushing back enough or can't seem to solve certain problems then thats a tool issue, either edit the tool system prompts or move to better tools or models.

Calling this 'skills' is disingenuous, this word was chosen by marketers and implies some kind of deeper learning. I'm not saying there's no value in tuning prompts, but your 'skills' should be managed in only 2 ways: 1. It's specific to your project, it's a README, or 2. It's specific to your tooling, it's part of config, system prompts etc.