Custom skills and hooks for coding assistants in daily work

Why teams struggle with coding assistants

Most teams hit the same problem first: every developer uses the assistant differently. One person writes careful prompts with project rules. Another asks for a quick fix with almost no context. A third pastes in a large file and hopes for the best.

The assistant follows whatever it gets, so the results swing from person to person. The code might run, but naming changes across files, tests get skipped, logs use the wrong format, and reviewers keep leaving the same comments on every pull request.

Repeated setup work makes it worse. Developers keep re-explaining the stack, the folder structure, the coding style, and the same review rules. Then they still have to fix imports, rewrite comments, add missing checks, and bring the final code back in line with team standards. Saving 10 minutes on generation is not impressive if cleanup takes 20.

This shows up a lot on small product teams. The CTO or lead engineer usually knows the right patterns, but those rules live in old chat threads, private notes, or one person's memory. New team members do not see them. Busy team members forget them. The assistant will not remember them unless someone pastes them in again.

The usual failure points are boring, but expensive. Developers use different prompt styles. Project context starts from zero in every session. Review rules appear after the code is already written. Repetitive work stays manual. Cleanup keeps landing on the same senior engineer.

That is where skills and hooks help. They turn scattered habits into shared daily behavior. Instead of hoping everyone remembers the same rules, the team gives the assistant a simple workflow it can follow every day.

What skills and hooks actually do

Teams rarely struggle because the assistant is weak. They struggle because too much stays in people's heads. Naming rules, test commands, folder structure, review notes, security checks, and release steps all compete for attention.

Skills and hooks solve different parts of that problem. A skill is a reusable set of instructions for work that comes up again and again. A hook is an automatic action that runs at the right moment, without anyone having to remember it.

A skill helps with tasks that still need judgment. You can give the assistant a skill for writing database migrations, drafting pull request summaries, following API naming rules, or creating tests in the style your team already uses. The skill does not do the whole job on its own. It gives the assistant the team's playbook, so the first draft starts much closer to acceptable.

A hook handles the steps that should happen every time. If a file changes, the hook can run formatting. Before a commit, it can run tests or check for secrets. After code generation, it can update docs or a changelog. People stop carrying those steps in memory, and the team misses fewer checks.

That split removes a lot of daily friction. Developers do not need to repeat the same instructions in every prompt. Reviewers spend less time pointing out the same fixes. New teammates pick up the project's habits faster because the assistant already works inside them.

Picture a simple request: add a new endpoint. The skill tells the assistant how the team structures handlers, errors, and tests. The hook runs the formatter and test command right after the change. One shapes the work. The other enforces the routine.

When teams use both, the assistant stops acting like a smart stranger. It starts acting more like a teammate who remembers the house rules every time.

What belongs in a skill and what belongs in a hook

The split matters because skills and hooks solve different problems. A skill tells the assistant how your team wants work done. A hook runs an action at a specific moment, without someone having to remember it.

Put anything that needs judgment, tone, or choice into a skill. That includes writing rules, review rules, and step-by-step recipes for common tasks. A good skill can say, "write tests first for bug fixes," "keep API handlers thin," or "summarize tradeoffs before changing schema design."

Hooks are better for work that should happen the same way every time. They can run formatters, lint checks, test commands, file validation, or a notification after a task finishes. If the team never wants to debate the step, a hook is usually the better place for it.

A simple rule your team can use

Ask one question: does this step need a person to decide something?

• If yes, put it in a skill.
• If no, put it in a hook.
• If the step blocks a commit or merge, prefer a hook.
• If the step explains how to think, review, or write, prefer a skill.

That rule keeps teams out of a common mess. People often cram too much into hooks, then wonder why the workflow feels rigid. Or they push automatic checks into skills, then nobody runs them consistently.

Leave manual steps manual when judgment really matters. Security review, architecture tradeoffs, naming for public APIs, and customer-facing copy still need a human to choose. The assistant can help with options, but it should not pretend every call is automatic.

The line is usually clear. "When editing TypeScript, use our import order and comment style" belongs in a skill. "Run the formatter and type checker after file changes" belongs in a hook. "Message the team if deployment config changed" also belongs in a hook.

If a rule teaches behavior, make it a skill. If a rule enforces behavior, make it a hook. That small distinction saves a lot of friction later.

Start with the standards your team already uses

Most teams already have standards. They just do not live in one clean document. They show up in review comments, chat messages, old tickets, and in the habits of the most careful engineer on the team.

That is the right starting point. If the assistant follows rules your team already trusts, people will use it. If you dump a huge policy file on it, they will ignore it.

Write down the standards people repeat every week. Look for the comments that keep coming back in pull requests and release checks. Common examples are simple: run tests for the code you changed before opening a PR, add a migration when you change the database schema, never commit secrets or production URLs, update API docs when request or response fields change, and add basic error handling and useful logs for new background jobs.

Do not start with every rule your team has ever discussed. Pick the ones that create bugs, rework, or release delays when people skip them. A naming preference is annoying. A skipped migration, missing test, or leaked secret costs real time.

Then rewrite each standard in plain language. Long policy text does not help the assistant or the team. Short rules work better because they are easy to scan and easy to apply.

Good rule: "If you change a table or column, add a migration and a rollback note."

Less useful rule: "All database-related modifications should follow the approved process described in the engineering handbook."

Keep the first version small. Start with one or two rules for each area, such as code changes, database work, and deployment. Teams that try to encode everything at once usually end up with noisy prompts, brittle hooks, and people switching the whole thing off.

A good test is simple: if a rule saves review time every week, add it first.

Add project context the assistant can use

Skills and hooks work much better when they know your project the way a regular team member does. Generic instructions help a little. Project context changes the daily output.

Start with the small facts that shape most code reviews. A short note about folder layout, file naming, and how your team runs tests will prevent a lot of avoidable mistakes. If the assistant knows that API handlers live in one directory, React components follow a certain naming pattern, and the test command is pnpm test:unit, it stops guessing.

A useful context pack is usually small. It should include a simple map of the codebase, naming rules for files and functions, the commands for tests and linting, and the product terms your team uses every week.

Product language matters more than many teams expect. If your product says "workspace" and never "project," or "member" instead of "user," the assistant should follow that every time. The same goes for business rules. If a canceled subscription keeps read access for 30 days, or if invoices lock after export, write that down. Otherwise the assistant fills the gaps with common patterns that do not match your product.

New team members often miss the same awkward details, so record those too. Maybe dates must always use UTC. Maybe soft-deleted records still appear in admin search. Maybe a customer can belong to two accounts during a migration. Those are the details that create bugs, not the big architecture diagram.

In practice, the most useful context is short and close to the code, not buried in a long document. One page that stays current beats ten pages nobody reads.

Keep it fresh. If you rename modules, change test commands, or update product terms, update the skill or hook that day. Old context teaches old habits, and the assistant will repeat them fast.

Build a simple workflow step by step

Start with one task your team already does almost every day. A small bug fix works well. So does a tiny feature, like adding one field to a form or changing an API response.

Pick something narrow enough that one developer can finish it in a few hours. If the task is too big, you will not know whether the skill helped or whether the task was just messy.

Then write one skill that guides the assistant through the whole job. Keep it plain. Ask it to read the ticket, make a short plan, write the code, and run a self-check before it says the work is done.

A simple first version might look like this:

• Read the task and summarize the change in 3 to 5 lines.
• List the files you expect to touch before writing code.
• Make the change in small steps and flag any risky part.
• Check style, tests, and obvious edge cases before finishing.

Hooks should handle the repetitive parts people forget or rush through. Add a formatter hook after file edits. Add a test hook for the changed area. Add a commit check that blocks unfinished work, such as failing tests or missing lint results.

Do not roll this out to the whole team on day one. Ask one developer to use it on a few real tasks. A short pilot tells you much more than a long planning session.

Pay attention to the wording after those first tasks. Small changes matter. "Check tests" is vague, but "run unit tests for touched modules and report failures before commit" gives the assistant a clear job.

After three to five tasks, you should know what stays, what goes, and what needs tighter instructions. Then you can hand the workflow to the rest of the team with much less friction.

A realistic example from one workday

A small team gets a ticket at 9:10 a.m.: add CSV export to the customer list, but only for managers. It sounds simple. It usually is not. The export has to match existing field names, respect permissions, log the action, and avoid slowing down the page.

The developer opens the ticket and starts the assistant inside the repo. Before it writes a single line, the assistant loads the project skill for backend changes. That skill includes the team rules: use the shared permission helper, keep API errors in the existing JSON shape, write table-driven tests, and add audit logs for any data export. The assistant does not guess the team's habits. It reads them first.

With that context, the assistant drafts a small plan, then writes the handler, the service method, and a test file. It also follows the project rule that CSV exports run as a background job if the result set gets too large. A human still decides the threshold. In this case, the developer keeps the first version synchronous because the customer list is capped at 2,000 rows and the current server can handle it.

The first save triggers local hooks. One formats the code. Another runs linting. A third runs the narrow test set for the files that changed. A fourth checks that any new endpoint has a permission test. The assistant fixes two issues right away: a missing audit log field and a test name that breaks the team's naming pattern.

By lunch, the developer opens a merge request in GitLab with the code, tests, and a short summary generated from the diff. CI runs the full test suite and style checks again. The assistant suggests a note for reviewers about one edge case: exports with empty optional fields should keep column headers but leave cells blank.

A person still has the last word. The tech lead reviews the tradeoff around sync versus background export, checks whether managers from one tenant could ever export another tenant's data, and asks for one more test. The assistant handles the edit quickly, but the judgment stays human. That split usually works best.

Mistakes that make the workflow harder

Most teams make the same mistake first: they pour every rule, reminder, and edge case into one giant skill. That looks tidy on paper, but it gives the assistant a bloated prompt and fuzzy priorities. A smaller skill for API work, another for test updates, and another for docs usually works better than one file that tries to control everything.

Too many hooks create a different problem. If a hook runs on every tiny action, people stop reading the output. After a week, the team treats the warnings like pop-ups and clicks past them in their head.

Hooks need a clear job and a clear moment. Run them when the cost of a mistake is real, not every time someone touches a file. A hook before a commit, schema change, or deploy often helps. A hook that interrupts every edit usually gets ignored.

Hidden scripts also cause trouble. A team adds a hook, the hook calls a script, the script calls two more scripts, and soon nobody knows who owns the logic. When that breaks, people waste an hour just tracing what happened.

Keep the moving parts easy to find and easy to explain. The team should be able to answer three plain questions: what does this run, when does it run, and who updates it?

Stale context is another slow failure. The codebase changes, folders move, naming rules shift, and old services disappear. But the assistant still reads last month's context and keeps writing code for paths that no longer matter.

That mismatch feels small until it happens five times a day. Then the workflow starts creating cleanup work instead of saving time.

The warning signs show up early:

• The assistant repeats rules that no longer match the repo.
• Developers mute hook output or work around it.
• Scripts fail, and nobody knows where they live.
• One skill file keeps growing because every new problem gets dumped into it.

Teams that keep these workflows useful do one thing well: they prune. They remove dead rules, split overloaded instructions, and update project context when the codebase changes. Clean workflow rules beat clever workflow rules almost every time.

A quick check before rollout

Run through a short reality check before your team starts using skills and hooks every day. A setup can look tidy on paper and still annoy people during real work.

If a new developer cannot understand the flow in about ten minutes, the setup is too hard. They should see where the skill lives, when the hook runs, what it changes, and how to skip or retry it when needed. If they need a long walkthrough, simplify the flow before rollout.

A good hook saves more time than it costs. That sounds obvious, but teams often miss it. A hook that waits 20 seconds before every commit, file save, or test run will get disabled fast. Keep the fast checks automatic, and move heavier work to moments where the delay makes sense.

Use a short checklist:

• Write down who changed each rule, when they changed it, and why.
• Check that every skill mentions real folder names, commands, and naming rules from the current project.
• Remove anything that refers to old scripts, old branches, or old package names.
• Test the full flow on one normal task from this week, not on a toy example.
• Watch one developer use it without help and note where they pause or guess.

Version history matters more than most teams expect. When a hook starts failing or a skill gives odd advice, someone needs to trace the change quickly. A short note in the repo often does the job.

Project context also needs regular care. If the assistant reads the wrong command or outdated folder structure, it will make confident mistakes. That is worse than having no automation at all.

The final check is simple: use the setup on real work. Fix a bug, add a small feature, rename a component, or update a test. If the flow feels slower, noisier, or harder to trust, stop and trim it before the full team adopts it.

Next steps for a small team

Start narrow. Pick one team, one repo, and one task people repeat every week. Pull request checks, test case writing, changelog updates, or release notes are all good places to begin. A small win is easier to see, and it gives the team a clear before-and-after.

If you try to encode everything at once, the setup gets messy fast. One focused workflow is enough to prove whether this fits your daily work.

For the first month, keep the measurement simple. Count how many review comments repeat the same standard issues. Track missed steps before merges or releases. Watch handoffs between developers, QA, and product. Note whether routine work takes less time than before.

These numbers do not need to be perfect. If review comments drop, fewer steps get skipped, and handoffs need less back-and-forth, the workflow is doing its job.

Someone also needs to maintain it. Assign one person to own the skills and hooks for a set period, even if that person only spends 30 minutes a week on updates. Standards change, repos change, and prompts go stale. Without ownership, teams keep using rules that no longer match the codebase.

Keep the documentation short. Write down what each skill does, when each hook runs, who updates it, and how the team can suggest changes. If that note fits on one page, people will actually read it.

If your team wants help setting this up, Oleg Sotnikov at oleg.is advises startups and small teams on AI-first development workflows, infrastructure, and Fractional CTO work. A short outside review can be enough to spot one useful starting point and avoid building a complicated system too early.

The best rollout is usually modest. Fix one repeated annoyance, measure the result, and expand only after the team trusts it.