Merge pull request #368 from TencentCloudBase/feature/manage-local-skills-extract

feat(skills): 🧰 add manage-local-skills workflow

Author: binggg

.agents/skills/manage-local-skills

@@ -0,0 +1 @@
+../../skills/manage-local-skills

.agents/skills/skill-authoring

@@ -0,0 +1 @@
+../../skills/skill-authoring

.claude/skills/manage-local-skills

@@ -0,0 +1 @@
+../../.agents/skills/manage-local-skills

.claude/skills/skill-authoring

@@ -0,0 +1 @@
+../../.agents/skills/skill-authoring

.codebuddy/skills/manage-local-skills

@@ -0,0 +1 @@
+../../.agents/skills/manage-local-skills

.codebuddy/skills/skill-authoring

@@ -0,0 +1 @@
+../../.agents/skills/skill-authoring

skills/manage-local-skills/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: manage-local-skills
+description: Analyze, standardize, validate, and sync locally maintained skills into agent skill directories with a `skills` CLI-aligned workflow. Use this skill when Codex needs to turn ad-hoc prompt or rules folders into reusable `SKILL.md`-based skills, install or sync one or more local skills from `./skills` into Claude, Cursor, CodeBuddy, Codex, or similar agent directories, or manage local skill path mappings and symlink or copy installation behavior.
+---
+
+# Manage Local Skills
+
+Manage locally maintained skills as reusable, standard skill assets.
+
+## What this skill does
+
+Use this skill to:
+
+- classify local sources as standard skills, non-standard skill-like folders, or mixed repositories
+- convert non-standard local materials into a standard `SKILL.md`-based structure
+- validate standard skill structure before installation
+- sync one or more local skills into one or more agent skill directories
+- maintain explicit agent and IDE path mappings for local skill installation
+
+## Do not use this skill for
+
+- publishing remote skills registries or package indexes
+- cloning skills from remote repositories
+- interactive marketplace search
+- generic documentation cleanup unrelated to local skill structure
+
+## Workflow
+
+1. Identify whether the user wants analysis only, migration, validation, mapping changes, or installation.
+2. If the source is not obviously standard, read `references/source-classification.md` and run `scripts/inspect-source.mjs` first.
+3. If migration is needed, read `references/migration-playbook.md` and convert the source into a standard skill folder before installation.
+4. Before mounting a skill, read `references/cli-alignment.md` and `references/install-workflow.md` to preserve the canonical-install model.
+5. Use `scripts/validate-skill.mjs` before and after installation when structure or path correctness is in doubt.
+6. If the target agent is new or unclear, read `references/mapping-extension.md` before adding or changing mappings.
+
+## Common requests
+
+- "Install this local skill into Claude and Cursor."
+- "Sync everything under `./skills` to Codex and CodeBuddy."
+- "Turn this prompts folder into a reusable skill."
+- "Link my local skills into the agent directories for this project."
+
+## Routing
+
+| Task | Read | Script |
+| --- | --- | --- |
+| Understand how this differs from or aligns with `skills` CLI | `references/cli-alignment.md` | |
+| Classify local sources and detect migration candidates | `references/source-classification.md` | `scripts/inspect-source.mjs` |
+| Convert non-standard local folders into standard skills | `references/migration-playbook.md` | `scripts/inspect-source.mjs` |
+| Install or mount local skills into agent directories | `references/install-workflow.md` | `scripts/install-skill.mjs` |
+| Add or update agent mappings | `references/mapping-extension.md` | `scripts/install-skill.mjs` |
+| Validate structure or installation results | `references/install-workflow.md` | `scripts/validate-skill.mjs` |
+
+## Operating rules
+
+- Treat `skills` CLI installation semantics as the behavioral baseline for canonical directory layout, scope handling, and symlink fallback.
+- Prefer analysis first when the source structure is ambiguous.
+- Do not execute arbitrary scripts from the source folder while inspecting it.
+- Keep local source directories distinct from canonical install directories.
+- Prefer symlinks when supported and safe. Fall back to copy when the user requests it or symlinks fail.
+- Make scope explicit: `project` means the current workspace, `global` means the user-level agent directory.
+- Ask the user to confirm before writing files, replacing existing installs, changing mappings, or converting a non-standard source into a standard skill.
+- If the user asks to sync multiple skills or multiple agents, summarize the planned batch operation before execution and wait for confirmation.
+- Call out differences whenever the requested behavior cannot fully match `skills` CLI.
+
+## Quick commands
+
+```bash
+node skills/manage-local-skills/scripts/inspect-source.mjs --input <path> --json
+node skills/manage-local-skills/scripts/validate-skill.mjs --skill-dir <path>
+node skills/manage-local-skills/scripts/install-skill.mjs --source-dir skills --skill <name> --agent cursor --scope project --mode symlink
+```
+
+## Minimum self-check
+
+- Is the source clearly classified as `standard`, `nonstandard`, or `mixed`?
+- Is the target skill structure valid before installation?
+- Is the canonical install path separate from the maintained source directory?
+- Is the selected agent mapping explicit and correct for the requested scope?
+- If symlink mode is used, is there a defined fallback to copy mode?
+- If behavior differs from `skills` CLI, did you state the difference clearly?

skills/manage-local-skills/references/cli-alignment.md

@@ -0,0 +1,69 @@
+# CLI Alignment
+
+Use this reference when local skill management must behave like the `skills` CLI as closely as possible.
+
+## Behavioral baseline
+
+The local management flow should preserve these `skills` CLI ideas:
+
+1. Keep a canonical installed copy of the skill separate from the maintained source folder.
+2. Install from the canonical directory into agent-specific directories.
+3. Prefer symlinks for agent-specific installs when supported.
+4. Fall back to copy mode when symlinks fail or when the user explicitly requests copying.
+5. Distinguish `project` scope from `global` scope.
+6. Treat universal `.agents/skills` targets and agent-specific targets with one shared model.
+
+## Canonical directory model
+
+For local management in this skill:
+
+- `project` canonical base: `<cwd>/.agents/skills`
+- `global` canonical base: `~/.agents/skills`
+
+The maintained source might be `skills/<skill-name>/`, but installation should copy it into the canonical base first.
+
+That separation matters because it:
+
+- keeps the maintained source independent from install state
+- avoids exposing one source folder directly to every agent
+- makes overwrite handling and verification more predictable
+
+## Agent target model
+
+After the canonical directory exists:
+
+- universal agents can use the canonical `.agents/skills` path directly
+- agent-specific targets should point to the canonical install
+- symlink mode should create a target entry that resolves back to the canonical directory
+- copy mode should materialize a standalone copy in the target agent directory
+
+## Alignment scope in this skill
+
+This skill intentionally aligns with local installation behavior, not the full CLI surface.
+
+Aligned in the first version:
+
+- canonical install directory
+- project and global scope selection
+- universal versus agent-specific target handling
+- symlink-first installation with copy fallback
+- path safety and conflict checks
+- the upstream `sanitizeName()` character policy: lowercase, allow `a-z`, `0-9`, `.`, `_`, replace other runs with `-`, trim leading and trailing `.` or `-`, fallback to `unnamed-skill`
+- the four IDE mappings used in this repo: Claude, Cursor, CodeBuddy, and Codex
+
+Not covered in the first version:
+
+- remote repository cloning
+- interactive TUI prompts
+- telemetry, audit, and leaderboard behavior
+- lock file restoration and update workflows
+
+## How to reason about differences
+
+If the requested behavior depends on unsupported CLI features, state that clearly and proceed with the local equivalent when possible.
+
+Examples:
+
+- Remote repository install requested: explain that this skill manages local sources and does not clone repositories.
+- Interactive selection requested: explain that this skill expects explicit paths, skill names, and target agents.
+- Lockfile restore requested: explain that this skill validates and mounts local skills, but does not rehydrate a lockfile workflow.

skills/manage-local-skills/references/install-workflow.md

@@ -0,0 +1,78 @@
+# Install Workflow
+
+Use this reference when mounting a local skill into one or more agent directories.
+
+## Installation model
+
+Treat installation as a two-stage process:
+
+1. Copy the maintained source into a canonical install directory.
+2. Expose that canonical install to one or more agent directories.
+
+This keeps maintained sources separate from runtime install state.
+
+## Scope
+
+Use `project` scope when the skill should live under the current workspace.
+
+- canonical base: `<cwd>/.agents/skills`
+
+Use `global` scope when the skill should live under the user environment.
+
+- canonical base: `~/.agents/skills`
+
+Always make scope explicit before writing files.
+
+Before performing a real install, confirm with the user when:
+
+- the operation will write files instead of dry-run only
+- multiple skills or multiple agents are involved
+- an existing canonical path or target path will be replaced or updated
+
+## Mode
+
+Use `symlink` mode by default when the filesystem supports it and the user does not require physical copies.
+
+Use `copy` mode when:
+
+- the user asks for independent copies
+- symlinks are unsupported or unreliable
+- a target environment rejects symlinks
+
+If symlink mode fails, report the fallback and switch to copy mode.
+
+## Conflict handling
+
+Before mounting a skill, check whether the canonical path or target path already exists.
+
+Report one of these outcomes clearly:
+
+- `overwrite`: replace the existing target with the new install
+- `skip`: leave the existing target untouched
+- `replace`: remove and recreate the target path
+- `update`: canonical target already exists and will be refreshed from the source
+
+Do not silently replace an existing skill path.
+Show the user the conflict summary first, then proceed only after confirmation.
+
+## Dry run
+
+Use dry run when the user wants analysis or confirmation before changing files.
+
+Dry run output should include:
+
+- source skill directory
+- canonical target path
+- agent target path or paths
+- selected scope
+- selected mode
+- detected conflicts
+
+## Validation after install
+
+After installation:
+
+- verify the canonical path exists
+- verify the target path exists
+- if symlink mode was used, verify the target resolves to the canonical path
+- if copy mode was used, verify that required files such as `SKILL.md` are present

skills/manage-local-skills/references/mapping-extension.md

@@ -0,0 +1,50 @@
+# Mapping Extension
+
+Use this reference when adding or updating supported agent or IDE targets.
+
+## Mapping rule
+
+Keep agent path rules in code, not in prose examples.
+
+Each mapping should define:
+
+- the stable agent key
+- the project-scope skill directory
+- the global-scope skill directory when supported
+- whether the target reuses the canonical `.agents/skills` directory
+
+## Minimum mapping shape
+
+```js
+{
+  key: {
+    skillsDir: '.agents/skills',
+    globalSkillsDir: '~/.example/skills'
+  }
+}
+```
+
+Treat a mapping as universal when `skillsDir === '.agents/skills'`.
+
+Examples:
+
+- Universal: `cursor`, `codex`
+- Agent-specific: `claude`, `claude-code`, `codebuddy`
+
+## How to add a new mapping
+
+1. Confirm the agent's project-level skill path.
+2. Confirm whether it supports a global user-level skill path.
+3. Add the mapping entry in `scripts/lib/agent-mappings.mjs`.
+4. Update tests to cover the new path resolution behavior.
+5. Update any reference material if the new target introduces a different install expectation.
+
+## When to reject a mapping
+
+Do not add a mapping when:
+
+- the agent does not have a stable local skill directory model
+- the requested path is only speculative
+- the path cannot be expressed safely with the current install model
+
+State the limitation clearly instead of guessing.