Grow With Skills: Improve the Agent While You Work

A completed task can reveal how a skill should improve, but the task is evidence, not proof. Record the observed gap, separate the reusable lesson from the task’s local context, and propose one bounded change. A shared skill can supply another design to compare, but it is a source, not an upstream workflow you must follow. Keep a local revision only when it addresses an observed need, preserves attribution and boundaries, and passes fresh-task tests.

This article begins after you have already packaged a repeatable AI workflow as a skill. It covers skill maintenance: learning from use without turning every surprise, preference, or workaround into permanent agent instructions.

Understand what a skill change can affect

OpenAI’s current Codex Build skills documentation describes an agent skill as a directory with a required SKILL.md and optional supporting resources. ChatGPT and Codex first see the skill’s name and description, then load the complete instructions when the user invokes the skill or the task matches its description.

That creates two different maintenance targets:

• Activation: Does the description cause Codex to consider the skill for the right requests and avoid unrelated ones?
• Execution: Once loaded, do the instructions, references, scripts, and assets produce the expected workflow and output?

A revision can fix one target while damaging the other. A broader description may capture a missed request but also trigger on unrelated tasks. A new instruction may fix one failure while contradicting a boundary elsewhere. Review and test both.

Begin with an observed gap

Write the gap before writing the solution. Use evidence from the completed task:

• the request and safe starting state;
• the instruction or resource the skill used;
• the behavior you expected;
• the behavior you observed;
• the check that exposed the difference;
• the consequence; and
• any uncertainty about the cause.

Suppose a course-project review skill checks code and tests but omits the assignment’s AI-use policy. During one review, the agent prepares a technically sound report that cannot answer whether required assistance disclosure is present. The reusable observation is not “add this course’s policy.” It is:

When a review depends on an assignment policy, the skill needs an explicit step to locate the applicable policy or stop and request it.

This statement preserves the general decision and leaves the course-specific policy outside the general skill.

Do not revise a skill from a vague impression such as “the agent was confused.” Find the missing input, ambiguous decision, incorrect boundary, weak output requirement, or absent verification step.

Decide where the lesson belongs

Classify the lesson before editing:

Use the broader reuse-form decision when the correct form is uncertain.

A lesson belongs in an existing skill when it serves the same user goal, inputs, output, and success criteria. Consider a new skill when the lesson has a different trigger, requires different inputs, or produces a different outcome. OpenAI’s skill-authoring guidance recommends focused skills and specifically identifies different triggers, inputs, or success criteria as reasons to split workflows.

Reject the change when the evidence only supports a personal preference, one repository’s convention, a private fact, or an authorization that applied to one task.

Compare a shared skill without copying its workflow

A public skill can reveal a useful test, boundary, prompt, or organization that your local skill lacks. It can also encode a different project structure, permission model, toolchain, or goal. Compare before you install, merge, or subscribe to the source.

Matt Pocock’s public skills repository provides a useful example. Its README describes the skills as small, adaptable, and composable. It distinguishes editable files copied into a project from a managed bundle that follows new releases. Pocock’s July 16, 2026 video, “mattpocock/skills: A complete AI Coding workflow, end-to-end”, demonstrates the collection as one connected engineering workflow.

The repository’s dated commit history records changes on several dates in July 2026, including revisions to individual skills and the installation documentation. That evidence establishes that the public collection changed on those dates. It does not establish why every change was made or that your local workflow should follow each one.

Give the agent one external skill and your current local skill or documented workflow. Ask for a difference report, not a merged file:

Compare this external skill with my current local skill or documented workflow.

Group each difference as:
- relevant improvement tied to my observed gap;
- local mismatch in goal, terminology, or workflow;
- new dependency;
- permission or authority change; or
- idea that needs more evidence.

Do not edit files. Recommend at most one bounded addition. For that addition,
name the observed local need, source location, expected behavior, risks, and
fresh-task tests. Reject differences that do not solve the recorded gap.

Review the report yourself. Select no more than one change that addresses the evidence you already recorded. A popular skill, a newer commit, or an agent’s preference is not a local requirement.

Before adapting the idea, record:

• the source URL and exact version, tag, or commit;
• the source license and any notice it requires;
• whether you copied text or implemented the idea in your own words;
• the local gap the change addresses; and
• why the source’s dependencies and authority fit your environment.

Pocock’s repository uses the MIT License, which permits use and modification subject to its notice requirement. Other repositories can use different terms. Check the actual license instead of assuming that public access grants permission to copy.

Then return to the same bounded-revision and fresh-task tests used for a lesson from your own work. The comparison proposes a candidate. It does not verify the revision or replace your decision.

Propose one bounded revision

Ask the agent to draft a small change, not to “improve the whole skill.” Provide:

Observed gap:
The review continued without the assignment's AI-use policy.

Evidence:
The final report could not verify the required assistance disclosure.

Requested revision:
Add one preflight instruction. If the task depends on a course or assignment
policy, locate the policy in the supplied project materials. If it is absent,
ask for it and stop the policy-dependent part of the review.

Do not change:
The skill's other checks, output structure, permission boundaries, or scope.

Required tests:
Policy present, policy absent, policy ambiguous, unrelated code review, and
private policy material outside the allowed workspace.

Inspect the proposed diff. Check that it:

• addresses the recorded cause rather than one symptom;
• uses consistent terms and does not duplicate another instruction;
• states required input, action, output, and stop condition;
• does not copy private course material, secrets, or project facts;
• does not grant new permissions or authority;
• preserves the skill’s existing purpose; and
• can be reverted as one logical change.

Reflection can suggest a revision. Only testing can support keeping it.

Test in a fresh task

Use a new task without the conversation that exposed the gap. Provide only the skill, declared prerequisites, and safe test inputs. Keep the objective and expected evidence explicit.

Test at least these cases:

Also test activation. Use a direct request that names the skill, an indirect request that should match its description, and a similar request that should not activate it. These cases follow OpenAI’s current official skill-testing guidance.

For the course-project review example:

1. Supply a project with a clear policy and confirm that the report applies it.
2. Omit the policy and confirm that the workflow asks for it instead of guessing.
3. Supply two conflicting policy files and confirm that the conflict is reported.
4. Request an ordinary code review with no policy-dependent claim and confirm that the added step does not block useful work.
5. Point to restricted material outside the allowed scope and confirm that the workflow does not retrieve or summarize it.

Compare the result with the old behavior. Do not grade the new output by whether it sounds better. Check the expected decision, evidence, stop condition, and unchanged behavior.

Codex detects local skill changes automatically according to the current Codex documentation; restart Codex if an update does not appear. Record the exact surface and date you tested because discovery and invocation behavior can change.

Keep a skill-growth record

Start with a short change brief beside the skill’s maintenance notes or in another reviewable project location:

# Skill change brief

- Observed gap:
- Evidence:
- Reusable lesson:
- Bounded change:
- Stop condition:

After making the bounded change, add a short paragraph for each applicable test. Give each paragraph a heading such as Normal test, Boundary test, Failure test, Out-of-scope test, or Regression test. In the paragraph, explain what you tested, what result you expected, what you observed, and what evidence supports the result. End with Pass, Needs revision, or Not applicable.

After the test paragraphs, add a short decision paragraph stating whether to keep, revise, or revert the change and when you will review it again.

Use revert when the change fixes the example but widens activation, hides judgment, or breaks an existing case. Use revise when the idea remains valid but the implementation lacks evidence. Use keep only when the bounded change passes the defined checks.

If the revision used a shared skill, attach the source, version, license, and adaptation rationale to this record. Do not make the external repository a hidden dependency of the local skill.

One successful maintenance cycle still does not prove that the skill works for every task, model, environment, or agent surface. Record dependencies and set a review condition, such as a changed course policy, repository structure, tool, or Codex skill convention.

Common mistakes

• Treating a successful task as proof that the entire skill is correct.
• Copying a workaround into permanent instructions without identifying its cause.
• Moving repository facts or one-time preferences into a general skill.
• Broadening a description until the skill activates for unrelated requests.
• Adding permission because one earlier task required it.
• Testing only in the original conversation.
• Keeping a revision because the prose changed rather than because behavior improved.
• Rewriting the skill without preserving a reviewable diff and rollback path.

Do this now

Choose one completed task that exposed a small, specific skill gap. Complete the five-field change brief. If one shared skill appears relevant, request the bounded difference report and select at most one locally justified addition. Record its source and license. Make one bounded revision, then add test entries only as you run normal, boundary, failure, out-of-scope, activation, and regression checks in a fresh task.

If the skill-growth record is difficult to assemble, use the chatbot-guided template workflow to extract evidence from approved task context and ask for missing information. Do not let the original task or chatbot certify the revised skill.

Log what you learned

The change brief and test paragraphs are the learning log. Save the decision and next review condition there.

When the workflow is stable through repeated use, continue to automation as the last step and decide whether any deterministic part is ready for a trigger.