How to Write a Skill File for a Coding Agent Your Team Will Share

The trigger line

The trigger is the sentence that decides whether the agent reads the rest of the file. Write it with the vocabulary your tasks actually contain: file names, commands, error strings, ticket labels. "Use when a pull request changes a database migration" is a trigger. "Use when relevant" is not.

Compare a weak trigger with a usable one:

Weak:  Use for testing tasks.
Better: Use when the task mentions pytest, a file under tests/,
        or a test failure in CI output.

If your agent platform supports metadata fields, the trigger belongs in the description field as well, since that is what gets scanned before the body loads the Claude skill authoring guide.

The inputs list

Name every file, field, environment variable, or command output the agent must read before starting. This is the section that prevents the most common failure, which is an agent guessing at repository structure. Be literal:

• pyproject.toml for dependency versions
• the failing test's full output, not a summary
• docs/schema.sql for current table definitions
• the pull request diff, limited to src/

If an input is missing, say what happens. "If docs/schema.sql is absent, stop and report" is a stop condition, which is the next section.

Numbered steps in imperative mood

Write steps as commands, not descriptions: "Read", "Run", "Compare", "Write". Number them so a reviewer can point at step 4, and so the agent has a stable order. Keep the freedom level matched to the risk. Anthropic's guidance distinguishes high freedom (text instructions for tasks where several approaches work), medium freedom (a template or parameterized script), and low freedom (one exact command, no variation) for fragile operations like migrations the Claude skill authoring guide. A migration skill should be low freedom. A code review skill can be high freedom.

Stop conditions

This is the section teams skip and then regret. A stop condition ends the loop. Agent systems are built as trigger, action, and stop condition because without an explicit stop the loop either runs forever or stops at an arbitrary point the MindStudio explainer. Four stop conditions cover most engineering skills:

Write numbers, not adjectives. "Under 80 changed lines" can be checked. "Small diff" cannot.

The worked example

Include one real example: a short input, the steps applied, and the output a reviewer accepted. One good example does more for consistency than three paragraphs of explanation. Keep it short and redact anything sensitive. This is also where you encode team taste, such as naming conventions or where tests live, without spending tokens on a tutorial.

Agents discover skill files by convention. Builder puts skills in a provider folder per skill, such as .builder/fireworks/SKILL.md, with a definition file plus optional scripts and templates as sibling files the Builder.io comparison. The same guide describes progressive disclosure: the agent scans name and description at session start and reads the full body only when the skill is relevant, which is why the description deserves as much care as the steps.

VS Code's guidance on scope is the useful decision rule for shared repos: store instructions at the narrowest scope that matches how you want to share them, with workspace scope for project conventions shared with contributors and user scope for personal preferences the VS Code documentation. A skill the team should share goes in the workspace, committed to the repo. A skill one engineer likes goes in their user folder. Mixing the two is how personal preferences leak into team process.

A practical layout for a repository:

repo/
  AGENTS.md                 # short repo rules, always applied
  .agents/
    skills/
      adding-migration/
        SKILL.md            # front matter + the five sections
        example.diff        # the worked example
      fixing-failing-test/
        SKILL.md

The naming convention matters more than it looks. Anthropic recommends gerund-style names such as processing-pdfs or testing-code, and warns against vague names like helper or utils, because a vague name makes discovery unreliable the Claude skill authoring guide. adding-migration tells the agent and the human what the file is for in one word.

The failure mode is predictable. The team champion writes a good skill, a colleague copies it into a personal dotfile, edits two steps, and within a month there are four versions and no one knows which one the agent will load. The fix is ordinary software discipline applied to a text file.

Four controls prevent forks:

1. A semantic version in the file. version: 2.1.0 in the front matter. Bump the minor version for added steps, the major version when stop conditions change, because stop conditions are the contract.
2. A named owner. One person, in the file, who reviews changes. The champion model works this way: a named, time-allocated owner per team, distinct from a general AI enthusiast, and organizations that formalize the role get better practice adoption than those that leave it to volunteers the Visdom maturity guide. The same guide notes that the champion is the person who writes the agent instruction file and escalates blockers.
3. A pull request requirement. Skill changes go through review like code. A short checklist keeps reviewers honest, covering trigger wording, stop conditions, and whether the example still reflects accepted output.
4. A changelog line. One line per version, stating what changed and why, so the next reviewer can see the history in the file rather than in chat.

This is a change management problem more than a tooling problem. Lucid's survey data on AI implementation found cultural resistance at 27 percent, undefined parameters at 26 percent, and unclear best practices at 25 percent among the top reasons AI efforts fail the Lucid change management guide. A versioned skill file attacks the second and third directly: parameters become explicit stop conditions, and best practice becomes a reviewed document instead of tribal knowledge.

There is a further reason to centralize. Research summarized by Iternal attributes 70 percent of AI success to people and processes rather than technology, and describes champion networks as the mechanism that turns a single person's working prompt into a repeatable team workflow the Iternal change management framework. A shared, versioned skill file is the artifact that makes that repeatable. The OpenAI champion guidance describes the same job in its own words: champions help move an organization from individual experimentation to repeatable, useful ways of working, and Activators build or adapt AI workflows for their team the OpenAI champion role resource. Writing the file is how the champion's knowledge survives their vacation.

Take a support engineering team with eight developers and a recurring task: updating a database migration when a model changes. Assume today each change takes one developer about 40 minutes of reading conventions, checking the schema, and writing the migration and its test, and that roughly five such changes land per week. That is 200 developer-minutes weekly, about 3.3 hours.

With a skill file, the agent reads the schema file and the conventions, writes the migration and a test, and stops when the test passes or the diff exceeds 80 lines. Suppose the developer now needs 15 minutes to review what the agent produced and answer any stop-condition question. That is 75 developer-minutes weekly, a saving of 125 minutes. Over a quarter of 13 working weeks, the team recovers roughly 27 developer-hours, which is about three and a half working days of one engineer's time.

Two cautions on that arithmetic. First, the saving depends on the output being accepted at the same quality. Track rejected diffs for the first month and count them, because a skill that produces diffs people reject is costing time rather than saving it. Second, the maintenance cost is real. Budget about an hour per skill per month for the owner, mostly reviewing pull requests and updating the example when conventions shift. A skill used weekly by eight people amortizes that easily; a skill used once a month does not.

The decision rule that follows is simple. Write a skill file when the task recurs at least weekly across more than one person and the conventions are stable enough to write down. If the conventions are still changing every sprint, the skill will churn faster than it saves, so wait.

One more practical point on measuring: the number to watch is not how many times the skill was loaded but whether stop conditions fired. If "diff over 80 lines" triggers on most runs, the scope in the trigger is too broad. If it never triggers, the limit is loose or the file is unnecessary.

For teams that want the same discipline across many skills, a shared platform helps. Quanta Inference gives you text, image, video, audio, and embedding models through one OpenAI-compatible API, which keeps agent experiments on one key and one billing line while you are still deciding which skills to keep: Quanta Inference.

Use this table in the pull request description. Each row is a yes or no, and a no blocks the merge until answered.

The last row is the one that keeps a skill library from bloating. Anthropic's guidance is blunt that models are already capable and that you should add only context the model does not already have, challenging each piece for its token cost the Claude skill authoring guide. The same discipline applies to what you copy into a skill. If it is already in the repo rules file, link to it rather than repeating it.

When the team has several skills working and wants to carry the pattern beyond coding agents into research, analysis, or document production, the natural next step is handing the same trigger-inputs-steps-stop structure to a specialist that reads your context and returns finished work: Quanta Experts.