1. Why More Skills Can Make Results Worse

In AI coding assistant usage, a recurring pattern appears: when only a few capabilities are enabled at first, task completion is usually acceptable. As more skill packs are added, the system begins to lose context, fail to use the right skill at the right time, or apply the wrong skill when it should not. This is not usually a model capability regression. It is a system-level resource competition problem that becomes more visible as the number of enabled skills increases. There are three main causes.

1. Context budget is a scarce resource, not free memory. Every enabled skill contributes metadata at the start of a session, including its name, purpose description, and constraints. The model must use this metadata to decide whether a skill should be activated. More skills mean a larger decision space and diluted attention. The budget available for understanding code, requirements, and error messages is squeezed, resulting in shallower analysis and faster forgetting. The tradeoff is asymmetric: the benefit of each additional skill tends to diminish, while its cost grows linearly or even superlinearly.

2. Overlapping trigger descriptions cause mis-triggering and conflicts. Skills are usually distinguished by natural-language descriptions. When multiple skills contain highly overlapping keywords such as “inspect code,” “optimize performance,” or “generate tests,” the model’s selection becomes unstable. The same task may use skill A one time and skill B the next time, producing inconsistent output style, checklist items, and modification scope. A worse case is cascading triggers: skill A invokes skill B after finishing, and skill B modifies a file that skill A just handled. The final output becomes difficult to attribute and hard to review.

3. Maintenance cost and security exposure are systematically underestimated. Each skill is an instruction that may be executed automatically. Some skills also include scripts, external dependencies, or network access. Installing ten unreviewed skills is equivalent to introducing ten uncontrolled execution paths into the development environment. Common consequences include dependency version drift, silent script failures, and permissions beyond what is actually needed. When skills are not trusted, prompt injection risk also increases because the instructions may induce unsafe operations.

2. Progressive Disclosure: Skills Are Loaded in Layers

Before reducing skills, it is important to understand how skills are loaded. The common industry pattern is progressive disclosure, which can be described in three layers:

• Layer 1: Metadata. This stays resident and contains only the name and a one- or two-sentence description of the purpose. Its only job is routing: deciding whether the skill should be expanded.
• Layer 2: Main instructions. This is loaded only when the skill is judged relevant. It contains operation steps, constraints, and acceptance criteria.
• Layer 3: Supporting resources. These include scripts, templates, reference materials, and sample data. They are read on demand when instructed by the main instructions.

This structure explains a key conclusion: the “quantity cost” of skills occurs mainly at Layer 1. A skill with only a vague description still occupies routing budget but does not provide a clear boundary. It is the least efficient type. Therefore, the point of reduction is not simply to cut the number of skills, but to remove entries that occupy routing space without providing clear value.

3. A Practical Selection Framework: Score Skills Before Keeping Them

Do not judge skills by whether they “feel useful.” Use quantifiable dimensions. It is recommended to score each candidate skill from 1 to 5 on the following three dimensions:

Dimension	Meaning	Decision basis
Usage frequency	Number of actual triggers in the past month	Count from session records rather than relying on impression
Individual value	Time saved or error rate reduced compared with not using the skill	A valid comparison is required; otherwise, the value is treated as zero
Maintenance and risk cost	Number of external dependencies, permission requirements, and failure frequency	Higher dependencies and broader permissions mean higher cost

Based on these scores, skills can be handled in four ways:

1. High frequency × high value → Always enabled. These are core assets and should be refined carefully.
2. Low frequency × high value → Conditionally mounted. Place them at team or project scope so they apply only to specific repositories or technology stacks, not globally.
3. Low frequency × low value → Archive. Keep them in the repository but do not load them by default. They can be introduced manually when needed. This is safer than deletion and preserves traceability.
4. High cost × no comparison evidence → Remove. This is especially true for skills that heavily overlap with the general model’s built-in capabilities, duplicate the responsibilities of other skills, depend on unstable external services, or have never been validated in practice.

A common health indicator is this: the total metadata of always-enabled skills should remain a very small portion of what a single session can stably handle, leaving enough budget for the task itself. It is better to have fewer, more precise skills than many vague ones.

4. A Minimal Viable Skill Set by Engineering Stage

A more useful question than “How many skills should be installed?” is “What kind of skill does each engineering stage need?” The following set is a proven skeleton organized around the software delivery pipeline. Each item includes its applicable conditions and boundaries.

1. Repository understanding and localization. This is used to answer questions such as “Where is this feature implemented?” and “Which modules are involved in this flow?” The value is not search itself, but verifiable evidence: file paths, key functions, and call relationships. Answers without paths and line numbers should be considered invalid. This constraint significantly reduces later hallucinations.

2. Pre-change impact check. Before modifying code, this skill should produce an impact list: which files will be touched, which interfaces are involved, which callers are affected, and whether database schemas or configuration changes are required. It exposes the most expensive mistake early: making changes in the wrong place after work has already started. The boundary must be explicit: analysis only; no file modifications. This prevents overlap with later implementation skills.

3. Pre-commit quality gate. This covers static checks, formatting validation, and dependency declaration verification. The key design is scripts first, natural language second: anything that can be judged by automated tools should not be left to the model to “take a look.” The model should explain failure reasons and suggest minimal fixes.

4. Test generation and regression. The input should be explicit: changed functions and branches. The output should be test cases covering normal paths, boundary values, and abnormal inputs. The cases must provide a way to construct them without relying on a real external environment, such as using test doubles, stubs, or in-memory implementations. A constraint should also be added: do not generate meaningless assertions merely to improve coverage. Otherwise, the result will be tests that look complete but are actually ineffective.

5. Troubleshooting and dependency diagnosis. This applies to error stack traces, build failures, and dependency conflicts. The core requirement is a three-stage structure: hypothesis → verification → conclusion. First list possible causes, then provide executable verification commands for each, and finally explain the basis for the conclusion. Changing configuration without verification should be prohibited.

6. Knowledge and decision recording. This turns one-time troubleshooting conclusions into repository documentation. It has the highest long-term value and is often the most neglected. It should output to an agreed directory, include a date and applicable scope, and avoid leaving conclusions scattered across chat logs.

These six items are a general skeleton. The exact number of entries should be tailored to the team’s actual delivery pipeline. If the team does not have an independent data-analysis stage, there is no reason to install a data-related skill just to make the set look complete.

5. Writing Quality Matters More Than Quantity

For the same skill, how well it is written can matter more than whether it is installed. The following six rules are hard standards when reviewing skills:

• Single responsibility. One skill should solve one class of problem. If the description contains multiple goals connected by “and,” it should be split.
• Clear trigger conditions and counterexamples. Saying “when to use it” is not enough. It is also necessary to state “when not to use it.” Counterexamples are the most effective way to suppress mis-triggering.
• Verifiable acceptance criteria. Describe outputs with statements that can be judged as pass or fail, rather than using unfalsifiable adjectives such as “high quality” or “elegant.”
• Prefer scripts over prose. Deterministic operations should be handled by code. The model should only handle parts that require judgment. This saves context and greatly reduces error rates.
• Least privilege and replaceable dependencies. Declare only the necessary capabilities. External service calls should be replaceable with test doubles; otherwise, the skill may fail directly in offline or restricted environments.
• Versioning and change history. A skill is an executed instruction and therefore a code asset. It must have review, versioning, and rollback.

The following is an illustrative metadata structure. It is only used to explain field design and does not correspond to any specific framework specification:

name: pre-commit-gate
when_to_use: >
  When the change is complete and before commit, use this skill to run static checks, formatting validation, and dependency declaration checks.
when_not_to_use: >
  When the modification plan is still undecided; when the task is only code reading or Q&A; when the CI pipeline already runs equivalent checks and local dry runs are unnecessary.
inputs: List of files changed in this submission
outputs: Check results + minimal fix suggestions for failing items
tools_required: Read-only file access, local command execution (allowlist only)
acceptance: >
  1) List the checks actually executed and their results;
  2) For each failure, provide the file path and reason;
  3) Do not modify any source file.

Pay attention to the when_not_to_use and acceptance fields. They address the two most common problems: mis-triggering and lack of acceptance criteria. Yet they are also the fields most often omitted.

6. Governance: Make Lean Selection Sustainable

Lean selection is not a one-time cleanup. It needs a mechanism to sustain it.

Scope layering. At least three scopes are needed: personal global (a very small number of truly cross-project capabilities), team-level (unified quality standards and commit conventions), and project-level (content strongly tied to a specific repository’s technology stack). The principle is: the more specific the content, the lower its scope. Global scope should retain only generic and high-frequency entries.

The manifest is code. The enabled skills, their sources, and their versions should be written into a manifest file in the repository and placed under version control. The manifest should be reviewed like ordinary code. Example:

# skills.manifest - skill assembly manifest (illustrative)
scope: team
skills:
  - name: repo-navigator
    source: internal-registry/repo-navigator
    version: 1.4.2
    mode: always          # always enabled
  - name: db-migration-check
    source: internal-registry/db-migration-check
    version: 0.9.0
    mode: conditional     # enabled only when changes touch the migration directory
    condition: "changed_paths matches 'migrations/**'"

A manifest provides three direct benefits: reviewability, rollbackability, and auditability. When performance degrades, it is easier to identify which manifest change introduced the regression.

Use an evaluation set instead of intuition. Select 15 to 30 representative questions from real historical tasks. Cover both high-frequency scenarios and typical failure scenarios, and turn them into a fixed evaluation set. After each skill configuration change, run the set and record four metrics: first-pass success rate, average number of rework rounds, number of mis-triggers, and average context consumption. Without these numbers, whether “lean is effective” remains a matter of opinion.

Observability. Record the time of each skill trigger, an input summary, the output conclusion, and the user’s subsequent action: accept, modify, or abandon. Log aggregation and analysis can use general cloud logging services, object storage, and monitoring/alerting capabilities; there is no need to build everything in-house. The observation period is recommended to be two to four weeks. Shorter periods make the data too sensitive to random factors.

7. Letting Agents Assemble Skills: Feasibility and Boundaries

Letting an agent read a manifest and install all skills at once is feasible and more efficient than configuring each skill manually. However, this approach works only if the risk surface is controlled, not if the review step is skipped.

What can be delegated to the agent: reading the manifest, batch-installing skills, verifying directory structure completeness, checking whether dependencies are present, generating an installation report, and detecting naming conflicts or overlapping descriptions. These are mechanical and verifiable tasks. An agent is often more reliable than manual work for these tasks.

What cannot be delegated to the agent: judging whether a source is trustworthy, judging whether an instruction contains dangerous operations, and judging whether permission requests exceed what is necessary. These three judgments must be made by humans, and they must be made before installation.

Recommended process:

1. Humans review the manifest sources and allow only trusted sources, such as an internal registry or team-owned repositories.
2. The agent performs the installation and outputs an operation log for each step.
3. After installation, automatic verification is run: whether metadata is complete, whether trigger descriptions overlap, and whether script dependencies can be resolved.
4. Run the evaluation set and compare the results with the pre-installation baseline. Confirm that there is no regression before merging the manifest change.

There are three key risks. An untrusted source means execution permission is given to unknown code. Content injection means skill instructions may contain induced commands. Silent failure means the installation appears successful but the skill is not actually effective, leaving the team operating under a false assumption. The corresponding measures are source allowlists, manual review of instruction bodies before installation, and mandatory post-installation verification.

8. Common Myths and a Four-Week Rollout Plan

Several claims are worth challenging:

• “A complete set looks professional.” Capability density comes from how well skills are written, not from their number.
• “More detailed descriptions are always better.” Longer Layer 1 metadata increases routing cost and can reduce accuracy.
• “If results are poor, add another skill.” Poor results are more often caused by unclear skill boundaries or missing acceptance criteria.
• “Installing skills has no downside.” Every skill consumes budget, permissions, and maintenance effort. The downside is real.

A four-week rollout plan:

• Week 1: Inventory. Export all currently enabled skills, count actual trigger frequency for each, and mark entries that have never been triggered.
• Week 2: Trim. Use the evaluation matrix to classify each skill. First archive low-frequency entries, keep only the core set of high-frequency and high-value skills, and add counterexamples and acceptance criteria for each retained skill.
• Week 3: Establish a baseline. Organize the evaluation set, run a pre-change baseline, and place the manifest under version control.
• Week 4: Validate and solidify. Re-test after the changes and compare the four metrics. Write the approved configuration into team standards and require future changes to go through manifest review.

In one sentence: the value of a skill set lies in clear boundaries, verifiable acceptance criteria, and sustainable maintenance, not in the number of skills. Saving routing budget for the parts that truly require judgment is the key to keeping an agent stable.