Adapt Shared Agent Skills to Your Own Workflow

An existing agent skill is a starting point, not an authority. Before you install, combine, or adapt one into a skill you already maintain, inspect what it assumes, compare it with your current workflow, and test the meaningful difference on a small safe task.

Keep at most one bounded adaptation at a time. Preserve the source, version, license, rationale, rejected alternatives, and rollback path. A passing example is evidence about that task and environment. It is not proof that one skill is universally better.

Start by naming the local requirement

The Agent Skills specification defines a skill as a directory with a required SKILL.md and optional resources such as scripts, references, and assets. Current Codex guidance describes skills as packages of instructions and resources that are loaded progressively: a short description helps discovery, the full instructions load when the skill is activated, and supporting files are loaded when needed.

That format tells you how to inspect a candidate. It does not tell you whether the candidate belongs in your workflow.

Write the local requirement first:

Repeated situation:
Current workflow:
Pain or missing capability:
Hard boundary:
Evidence that would justify a change:

For example:

I repeatedly ask an agent to review small Hugo drafts. I want it to check front matter and rendered links, but it must not publish, commit, or read private planning files unless I provide them. I will accept an adaptation only if it finds a deliberately broken internal link and preserves the publication boundary.

This statement gives you something to compare. “This skill looks more capable” is not a requirement.

A student claim: “This linting skill will catch mistakes before I submit”

Suppose a student finds a shared skill that claims to review a repository before submission. The useful question is not whether the skill is popular or long. It is whether the skill catches the mistakes the student cares about while staying inside the intended authority boundary.

Write the claim narrowly:

On a copy of my Markdown-and-code assignment, this skill will report one deliberately broken internal link and one formatting problem, will leave the files unchanged, and will stop when the required checker is unavailable.

The fixed test should contain a known-good page, a deliberately broken link, a formatting defect, and no credentials. Compare the skill with the student’s current checklist. Record which files it reads, whether it invokes scripts or network services, what it reports, whether it edits anything, and how it behaves when the checker is missing. A successful report is evidence about that fixture and harness. It is not proof that the skill catches every submission problem.

If the candidate adds a useful link-check step without changing the output contract, that may justify a bounded adaptation. If it silently edits files, uploads coursework, assumes a tool the student does not have, or claims a clean result after a checker failure, keep it separate or reject it. The test turns a vague promise into a decision the student can explain.

Choose the right starting case

Classify the work before comparing files.

The earlier reuse-form decision helps distinguish a skill from a note, checklist, or script. Package a Repeatable AI Workflow as a Skill covers the initial packaging decision. This article begins after you have found an existing candidate or have a concrete reason to compare one.

Do not combine skills merely because they share a topic. Combining them is justified only when each contributes a distinct, compatible part of the local requirement and the combined output remains reviewable.

When a new skill should improve your existing skill

One case deserves a separate branch: you already have a personal skill that mostly works, then you find another skill with an overlapping workflow or a useful feature. These are not two neutral candidates. Your existing skill is the baseline and owns your local purpose, terminology, output contract, and authority boundary. The newly found skill is a source of ideas to inspect.

Ask for a difference report, not a merged file:

Compare this newly found skill with my current local skill.

Group each difference as:
- a relevant improvement tied to an observed local gap;
- a local mismatch;
- a new dependency;
- a permission or authority change; or
- an idea that needs more evidence.

Do not edit either skill. Recommend at most one bounded addition.
For that addition, name the observed gap, source location, expected behavior,
risks, and fresh-task tests.

This is related to, but different from, Grow With Skills: Improve the Agent While You Work. The current article covers a source-led decision: a newly found skill suggests an improvement to your existing skill, so you inspect the overlap, preserve attribution and boundaries, and test one candidate addition. Grow With Skills covers an evidence-led maintenance decision: your own completed work exposes a gap, and you improve the skill from that observed behavior. Both paths require a bounded revision and fresh-task tests, but they begin with different evidence.

Do not let the new skill become a hidden upstream dependency. Copy or reimplement only the justified idea, record its source and license, and keep your local skill understandable if the external project changes or disappears.

Inventory each candidate before reading it as advice

Make a compact inventory for every candidate. Read the entire SKILL.md, then inspect referenced files only as needed to understand the workflow. Record what the skill actually contains rather than what its description suggests. Give the inventory a short title such as Skill inventory — [candidate], then answer these questions in short paragraphs:

• What task or wording should trigger the skill, and what inputs does it require?
• What sequence, heuristics, definitions, references, and examples does it provide?
• What scripts, tools, dependencies, and external services does it assume?
• Can it read, write, execute, publish, or contact anything? What permissions are actually stated?
• What artifact or report should result, and what evidence demonstrates that it worked?
• When should the agent pause, ask, refuse, or hand control back? Who maintains the skill, and which version, commit, or license identifies the source?

Use unknown when the candidate does not answer a question. A short paragraph is enough; do not create a Markdown table just to preserve the question list.

Treat missing information as a finding. “No permission boundary is stated” is different from “the skill has no permissions.” The first means you need to investigate the harness and execution environment before adoption.

Compare behavior, not size

Write a difference note after the inventory. Give it a short title such as Skill comparison — [candidate A] and [candidate B], then answer these questions in short paragraphs:

• Where do the candidates inspect the same input but produce different reports, and which output contract is easier to verify?
• Does one add a source-check step or address a local requirement without changing authority?
• Does either candidate edit files, use a tool, or assume a platform before the other asks for confirmation?
• Do the instructions conflict, and which source has authority?
• Which proposed improvement still needs a safe test rather than a preference?

Label each difference overlap, complement, authority change, local mismatch, conflict, or needs evidence in the paragraph where it appears.

Do not resolve a conflict by placing both instructions in one longer file. An agent may follow the contradiction inconsistently. Choose the authoritative rule, narrow the scope, or keep the candidates separate until a human decides.

The same caution applies to permissions. A skill that adds shell access, network access, file writes, or publication actions is not a small wording variation. It changes the authority boundary and deserves a separate decision.

Run a small comparison on a fixed task

An A/B-style test is useful when it compares one meaningful difference under the same conditions. It is not a model leaderboard.

Use a safe representative task:

1. Freeze the input files, prompt, working directory, tool availability, and starting state.
2. Define the expected output before running either candidate.
3. Run candidate A and candidate B separately, or run the current workflow as the baseline.
4. Save the outputs, tool actions, errors, duration if relevant, and human corrections.
5. Review both outputs against the same criteria.
6. Repeat one case that should fail or require a stop.

Use at least these test cases:

Record the comparison in a small table:

Task and fixed inputs:
Expected output:
Candidate or baseline:
Actual output:
Verification result:
Failure or trade-off:
Human judgment required:
Decision:
Rollback location:

If the harness has different discovery or activation behavior, label that limitation. A skill can be portable in file format while still behaving differently across agent products. Test the actual harness you intend to use.

Adapt narrowly and keep the diff visible

An adaptation should answer one local requirement. Make the smallest change that could satisfy it, then rerun the normal and boundary tests. If the idea came from a newly found skill, preserve the difference report and source record with the adaptation so you can distinguish an external proposal from evidence gathered through your own workflow.

Good adaptations include:

• replacing an assumed path with an explicit input parameter;
• adding a stop condition before a file write or external action;
• moving a long product-specific explanation into a reference file;
• adding a local verification command without changing the output contract; or
• clarifying which claims are observations, recommendations, or unresolved questions.

Risky adaptations include:

• adding new tools or permissions because they might be useful;
• copying repository-specific rules into a general skill;
• removing a human review gate to make the workflow faster;
• merging conflicting instructions without choosing an authority; or
• replacing the source skill’s license or attribution with your own label.

Keep a record like this beside your local copy or in your project log:

Source:
Source version or commit:
License and attribution:
Local requirement:
Changed files:
Permission changes: none / describe
Tests run:
Observed result:
Rejected alternatives:
Rollback path:
Review date:

If the skill came from a public repository, link to the exact source and inspect its license. The open Agent Skills repository is a useful example of why provenance matters: it documents the format, keeps a contribution history, and states separate licenses for code and documentation. That information belongs in your decision record, not in a vague “from the internet” note.

When starting from scratch is safer

Start with a new skill when the candidates have incompatible authority boundaries, depend on unavailable tools, or solve a different problem despite similar wording.

Use five required prompts for the first pass:

1. What repeated situation are you trying to handle?
2. What outcome should the agent produce?
3. What inputs are available and allowed?
4. What hard constraints or authority limits apply?
5. How will you verify the result?

Mark conditional details as unknown, not applicable, or return later. Do not fill gaps with invented context. Once the workflow is real, Grow With Skills covers how to improve it from evidence gathered during later work.

Common mistakes

• Choosing the longest skill. More instructions can mean more assumptions and more opportunities for contradiction.
• Testing only a happy path. A skill that succeeds once may still mishandle missing inputs or unsafe requests.
• Comparing different tasks. Without fixed inputs and criteria, the result mostly measures the setup.
• Broadening authority accidentally. New tools, network access, and writes require an explicit decision.
• Keeping no rollback. If you cannot restore the previous behavior, the adaptation is harder to evaluate safely.
• Treating a sample as a ranking. Record what happened in your environment and scope the conclusion accordingly.

Do this now

Choose one candidate skill and write the five-line local requirement record before editing it. If you cannot state the repeated situation, desired outcome, authority boundary, and verification method, you are not ready to adapt the skill.

Log what you learned

• What repeated workflow did you evaluate?
• Which candidate or baseline did you compare, and what was its source and version?
• What changed, what stayed unchanged, and which permissions were involved?
• Which normal, boundary, failure, out-of-scope, and regression checks did you run?
• What remains uncertain, rejected, or scheduled for later review?

Further reading

• Agent Skills specification
• Build skills with ChatGPT and Codex
• Agent Skills specification and documentation repository
• Package a Repeatable AI Workflow as a Skill
• Grow With Skills: Improve the Agent While You Work