how-to

name

how-to

description

Identifies the most suitable set of agent skills for a concrete task by semantically matching it against a large, curated skill library, then produces an implementation plan without executing it. Use when users want to discover, search for, or find agent skills; ask questions such as "How do I do X?", "Find a skill for X", or "Is there a skill that can do X?"; or express interest in extending the agent's capabilities. Also use when a user has described a concrete task, but the current system prompt and conversation provide no suitable tools, skills, or implementation approach, and the model cannot reliably complete the task from its own knowledge alone.

Create a Skill-Supported Plan

Let TASK denote the concrete task description currently provided by the user. Select skills and create a plan only for TASK; do not execute the plan in the current turn.

1. Confirm the Input and Boundaries

1. Confirm that TASK is non-empty and sufficiently specific to identify the goal. If the task description is missing, ask the user for it before starting any synchronization or matching.
2. The only permitted side effects are checking whether a local Git executable is installed and running the corresponding index and skill synchronization scripts specified by this skill, so that the index and the ultimately selected skills are available locally.
3. Do not create, modify, or delete the target deliverables of TASK; do not invoke implementation scripts from the ultimately selected skills; and do not carry out the plan on the user's behalf.
4. Explore only what is directly relevant to determining candidate skills' level of support and practical availability. Use read-only inspection for files mentioned in TASK, upstream candidate SKILL.md files, or repository metadata. You may also inspect the local runtime as needed, such as installed tools, development packages, dependencies, and relevant code. Exploration must serve skill selection; stop as soon as sufficient evidence is obtained, rather than expanding into general research.

2. Locate the Bundled Scripts and Synchronize the Index

1. Let SKILL_DIR be the skill directory that contains the current SKILL.md. Do not infer the script location from the current working directory or the Git repository.

2. Confirm that the following bundled scripts exist:

   • <SKILL_DIR>/scripts/sync_skills_index.py
   • <SKILL_DIR>/scripts/sync_skills_index_dulwich.py
   • <SKILL_DIR>/scripts/sync_skills.py
   • <SKILL_DIR>/scripts/sync_skills_dulwich.py

3. Before synchronizing the index, run git --version once and retain the result for the rest of the current workflow. Treat a zero exit status as Git being installed, and a nonzero exit status or command-not-found error as Git not being installed:

   git --version
   

4. If Git is installed, replace <SKILL_DIR> with the skill directory's actual absolute path, then run:

   python3 "<SKILL_DIR>/scripts/sync_skills_index.py"
   

5. If Git is not installed, run the Dulwich implementation instead:

   uv run "<SKILL_DIR>/scripts/sync_skills_index_dulwich.py"
   

6. Proceed only if the selected implementation exits successfully. “Less than 6 hours have elapsed; skipping update” counts as a successful result. If sync_skills_index.py fails and its error specifically indicates that the Git executable is missing or cannot be found, retry the index synchronization once with sync_skills_index_dulwich.py using the command in step 5, and treat Git as unavailable for the remainder of the workflow. Do not retry with Dulwich for any other error. If the Dulwich retry fails, or if the selected implementation otherwise fails, stop and report the specific error.

7. Confirm that the index root directory, ~/.bridgic/AmphiAgent/skills/skills-resolution, exists and that its category_list.json contains valid, parseable JSON. If synchronization fails, a file is missing, or the JSON is invalid, stop and report the specific error; do not silently use an outdated index.

3. Apply Cross-Cutting Domain Heuristics

1. Before matching categories, evaluate TASK against every heuristic listed below. Apply all matching heuristics; do not stop after the first match.
2. Carry matched heuristics through top-level category matching, second-level category matching, candidate gathering, and final skill-set selection. A heuristic may:
   • Add a complementary capability to search for;
   • Expand the top-level or second-level categories considered;
   • Prioritize particular candidate skills or implementation approaches.
3. Treat these heuristics as selection guidance rather than proof of capability. Do not select a skill unless its actual SKILL.md supports the intended role and it is practically available.

Domain Heuristics

• Presentations, video, and web: When TASK involves producing a presentation or PPT, video, or web page, also search for skills that provide suitable ready-made templates, starter kits, themes, or layouts.
• Feishu/Lark: When TASK involves reading or manipulating Feishu or Lark, prioritize category branches and candidate skills associated with lark-cli.

4. Match Top-Level Skill Categories

1. Read the index root's category_list.json in full and confirm that its top-level categories field is an array.
2. Semantically compare each top-level category's name and description against TASK's goal, inputs, expected deliverables, primary workflow, and constraints. Do not rely only on keyword overlap.
3. Prefer one top-level category that covers the task's primary goal. Select additional categories when TASK has distinct essential capabilities or a matched domain heuristic introduces a relevant complementary capability.
4. Record the part of the task covered by each selected category and why similar unselected categories are insufficient. Use these judgments for later filtering and the final explanation.
5. For normally selected categories, proceed to the next level only through their sub_category_files; do not scan other second-level category files.
6. Treat the top-level category named exactly Other as the sole exception. After confirming that it has no sub_category_files and directly contains a skills array, skip second-level matching and filter its skills directly by semantic fit with TASK. Because these entries contain only tuple metadata, conduct focused exploration of a small number of candidates under the rules in Section 6 when their names are insufficient for a reliable decision.
7. When extracting candidates from Other.skills, require every entry to contain the four valid string fields name, owner, repo, and skill_path exactly as provided. Do not guess, repair, or fabricate the tuple. Record the candidate source as Other (no second-level category).
8. If any top-level category other than Other lacks sub_category_files, or if Other lacks a direct skills array, treat it as an index-structure error and stop. Do not silently fall back to a different matching method.

5. Match Second-Level Skill Categories and Gather Standard Candidates

1. For each selected top-level category other than Other, read only the files explicitly listed in sub_category_files. Other already gathers candidates directly in Section 4 and does not enter this section.
2. Confirm that every filename begins with sub_category_, ends with .json, and resolves to a path still contained within the index root. If a file is missing, resolves outside the root, or has an invalid structure, stop and report the index problem.
3. Confirm that each second-level file has a top-level sub_categories array. Within the context of its top-level category, semantically compare TASK with each second-level category's name and description.
4. Prefer the smallest possible set of second-level categories. Keep multiple categories only when each covers a distinct essential capability or a relevant complementary capability introduced by a matched domain heuristic.
5. Extract candidates from the skills of the selected second-level categories. Each candidate must contain the four non-empty, valid string fields name, owner, repo, and skill_path exactly as provided; do not guess, repair, or fabricate the tuple.
6. Combine the standard candidates with the direct Other candidates and deduplicate by (name, owner, repo, skill_path). Retain the top-level and second-level category rationale for standard candidates, and an explicit “no second-level category” marker for Other candidates.

6. Determine the Minimal Skill Set

1. First decompose TASK into:
   • Required capabilities needed to complete the task;
   • Recommended complementary capabilities introduced by matched domain heuristics. Then assess each candidate's coverage of both groups and any hard gaps.
2. First ask whether one candidate can probably complete the required capabilities end to end and cover any materially useful complementary capabilities. If so, select only that candidate by default.
3. Select multiple skills when no single skill covers the required capabilities, or when a matched domain heuristic identifies a separate skill that adds concrete and material value.
4. When the candidate names, category descriptions, or current-environment information are insufficient for a reliable decision, conduct bounded, read-only exploration. In addition to inspecting the candidate's upstream SKILL.md, documentation page, or files directly related to a key capability, you may search locally installed command-line tools, executables, development packages, project dependencies, source code, and related project code as needed. Use this evidence to determine whether the candidate skills can complete the task in the current environment, whether their capabilities overlap, and whether hard gaps remain. Investigate only specific questions that could change the choice, and stop as soon as sufficient evidence is obtained.
5. Do not select weakly supported skills merely to fill out the set. If no candidate can genuinely complete TASK, handle it as “no suitable skill.”

7. Synchronize and Read the Final Skills

1. Convert each final selected skill tuple into four ordinary command-line arguments in the exact order name owner repo skill_path. Add one --skill occurrence per selected skill. Quote each argument using the active shell's ordinary argument-quoting syntax when needed, but do not serialize the tuples as JSON or embed JSON in the shell command.

2. Reuse the Git availability result recorded while synchronizing the index in Section 2. Do not run git --version again.

3. If Git is installed, use the native Git implementation. Repeat --skill for every selected skill:

   python3 "<SKILL_DIR>/scripts/sync_skills.py" --skill "<name>" "<owner>" "<repo>" "<skill_path>" --pretty
   

4. If Git is not installed, use the Dulwich implementation with the same repeated --skill arguments:

   uv run "<SKILL_DIR>/scripts/sync_skills_dulwich.py" --skill "<name>" "<owner>" "<repo>" "<skill_path>" --pretty
   

   For multiple selected skills, append another --skill "<name>" "<owner>" "<repo>" "<skill_path>" for each one. Do not use OS-specific JSON escaping.

5. Use the output from the implementation selected by Git availability. If sync_skills.py fails and its error specifically indicates that the Git executable is missing or cannot be found, retry the skill synchronization once with sync_skills_dulwich.py, passing exactly the same repeated --skill arguments and --pretty option shown in step 4, and treat Git as unavailable for the remainder of the workflow. Do not retry with Dulwich for any other error. If the Dulwich retry fails, or if the selected implementation otherwise fails, report the specific error and do not claim that the required skills are available.

6. Check that the output's top-level status is succeeded, and confirm that every result is not failed and contains local_path. If synchronization of any required skill fails, do not claim that it is available; report the failed stage and reason. Continue only if the remaining successful skills still fully support the plan.

8. Present the Plan

1. Provide one recommended plan by default. Add alternatives only when genuine tradeoffs exist.
2. Each plan must include at least:
   • The plan's goal and applicability conditions;
   • The selected skill tuples and their respective roles;
   • A step-by-step implementation process based on the skill contents you read;
   • Expected inputs, deliverables, and acceptance criteria;
   • Key risks, unknowns, and decisions required from the user.
3. Briefly list the matched top-level and second-level categories so that the selection path is auditable. If a skill comes directly from Other, explicitly state that the branch has no second-level category and was matched directly from Other.skills. Do not dump the entire candidate list.
4. Briefly list the matched domain heuristics and explain how each changed the category search, candidate priority, or final skill set. If a matched heuristic did not change the final selection, state why.
5. Clearly distinguish capabilities directly supported by the skill content from reasonable additions inferred from TASK. Do not claim that a skill has capabilities not reflected in its SKILL.md.
6. Explicitly state: “This turn provides a plan only; it has not been executed.” You may close by asking whether the user wants to execute the recommended plan in the next step.

9. Handle the Absence of a Suitable Skill

If no skill is genuinely capable of completing TASK after both standard two-level matching and direct Other matching, explain:

1. The closest top-level and second-level categories; if Other is closest, note that it has no second-level category;
2. The key capability still missing from the closest candidates;
3. Why no skill was selected by force.

Do not fabricate skill support or execute a generic workaround. You may ask whether the user would like a general plan that does not depend on indexed skills in the next step.