*"hjdZddlZddlZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z ddlZddlmZej"eZej(dZhdZd ed e e ee ffd ZGd d Zy)uR Skill Manager for SkillClaw skill retrieval, injection, and local persistence. Loads skills from a directory of skill subdirectories using the AgentSkills- compatible format (shared with OpenClaw / Pi coding-agent): memory_data/skills/ skill-name/ SKILL.md <- YAML frontmatter + markdown body scripts/ <- optional executable scripts references/ <- optional reference docs assets/ <- optional assets (templates, images, etc.) another-skill/ SKILL.md Each SKILL.md must have YAML frontmatter with at least ``name`` and ``description``:: --- name: debug-systematically description: "Use when diagnosing a bug. Gather evidence before forming hypotheses. NOT for: simple typo fixes." metadata: { "openclaw": { "emoji": "🔍" }, "skillclaw": { "category": "coding" } } --- # Debug Systematically ... Frontmatter fields ------------------ Required: name lowercase-hyphenated slug description rich trigger description — what, when to use, when NOT to use Optional: metadata nested dict; ``openclaw`` block for OpenClaw gating/install, ``skillclaw`` block for SkillClaw-specific fields (``category``) category (legacy) — if present and ``metadata.skillclaw.category`` is absent, used as fallback; defaults to ``"general"`` Valid categories: general, coding, research, data_analysis, security, communication, automation, agentic, productivity, common_mistakes N)Counter)AnyDictOptional)list_skill_bundle_pathsz^[a-z][a-z0-9-]{1,63}$>namecategorymetadata descriptionpathreturnc t|d5}|j}dddj dsy|j dd}|dk(ry|d|j}||d zdj} tj|xsi}t|tsyt|jd d j}t|jd d j} |r| stj d|y|jd} | t| tsd} d} | xsijdi} t| tr.| jdrt| dj} n-|jdrt|dj} tj |j#j%dd|| | |t&j(j+|d} | r| | d<|j-Dcic]\}}|t.vs||}}}|r|| d<| S#1swY1xYw#t$r!}tj d||Yd}~yd}~wwxYw#tj$rtj d |i}Y"wxYwcc}}w)aParse a SKILL.md file (AgentSkills / OpenClaw compatible format). Returns a dict with keys: name, description, category, content, and optionally metadata. Extra frontmatter fields (e.g. ``homepage``, ``user-invocable``) are preserved verbatim so they survive round-trip writes. Returns ``None`` if the file is missing required fields or has no frontmatter. Category resolution order: 1. ``metadata.skillclaw.category`` 2. top-level ``category`` (legacy) 3. ``"general"`` (default) utf-8encodingNz$[SkillManager] could not read %s: %sz---z ---z-[SkillManager] invalid YAML frontmatter in %sr r u:[SkillManager] skipping %s — missing name or descriptionr general skillclawr )idr r r content file_path_extra_frontmatter)openreadOSErrorloggerwarning startswithfindstripyaml safe_load YAMLError isinstancedictstrgethashlibsha256encode hexdigestosr realpathitems _CORE_FM_KEYS)r fraweend_idxfm_textbodyfmr r r r sc_metaresultkvextras 2/root/.hermes/SkillClaw/skillclaw/skill_manager.py_parse_skill_mdrBKs| $ ) Q&&(C  >>% hhw"G"}!Gn""$G w{}  # # %D ^^G $ * b$  rvvfb! " ( ( *Dbff]B/0668K {SUYZvvj!HJx$>H~2"";3G'4 W[[%<wz*+113  r*~&,,.nnT[[]+557<"WW%%d+ F%z!hhj CdaA],BQT CE C ',#$ My   =tQG >>FM L DsK III<J -J;>J;II J%JJ +J87J8c neZdZdZ dEdedededeefdZdefd Zdeeeee fffd Z dFd Z dFd Z d e eddfdZd e ededdfdZdedefdZdeeeee fffdZdeee ffdZde efdZdeeeeefdffdZdefdZdedefdZdedefdZdFdZdefdZdZe deee fdefdZ!defd Z"d!ededefd"Z# dGd#e ed$ed%ed&ede ef d'Z$d(ed%ede efd)Z%dHd(ed%ede efd*Z&de efd+Z'deeeeefffd,Z(dedefd-Z)e d.edefd/Z*d0e edefd1Z+d0e edefd2Z,e dId3ed4edefd5Z- dJd6ed4edefd7Z.d8eddfd9Z/dedefd:Z0dKd;e edZ2deddfd?Z3dLd@eeddfdAZ4de5fdBZ6de7fdCZ8defdDZ9y)M SkillManageruLoads skills from a directory of AgentSkills / OpenClaw compatible skill folders. Each skill is a subdirectory containing a ``SKILL.md`` with YAML frontmatter (``name``, ``description``, optional ``metadata``) and a Markdown body. Supports two retrieval modes: * ``"template"`` – flat effectiveness-ranked retrieval, zero latency * ``"embedding"`` – cosine similarity via SentenceTransformer N skills_dirpublic_skill_rootretrieval_modeembedding_model_pathc l|dvrtd|dtjj|st d|||_|j |_||_|xsd|_ d|_ d|_ d|_ |j|_|j|_|j#|_d|_|j)}t*j-dt/|jj1dg||t3||d k(r|j5yy) N)template embeddingz7retrieval_mode must be 'template' or 'embedding', got ''zSkills directory not found: zQwen/Qwen3-Embedding-0.6BrzA[SkillManager] loaded %d skills from %s | mode=%s | categories=%s all_skillsrK) ValueErrorr1r isdirFileNotFoundError _skills_dirr%_public_skill_rootrGrH_embedding_model_skill_embeddings_cache generation _load_skillsskills_compute_skills_fingerprint_skills_fingerprint _load_stats_stats _stats_dirty_category_countsr!infolenr,r*_compute_skill_embeddings)selfrErFrGrHcountss rA__init__zSkillManager.__init__s% !: :VWeVffghi iww}}Z(#&B:,$OP P%"3"9"9";,$8$Wg}|jD]o} tj|}|j tj j |t|jt|jfqt|S#t$rYwxYwN) rr1statr rr r2int st_mtime_nsst_sizetuple)ra fingerprintr rs rArXz(SkillManager._compute_skills_fingerprint>s24 ((* D wwt}   GG$$T*(() %  [!!  sB BBc tjj|jtjjtjj tjj dddk(S)N~z.hermesrW)r1r r2rQrf expanduserrgs rArz"SkillManager._is_hermes_skill_rootNsXww 0 01RWW5E5E GGLL++C0)X F6   rdrct|jddxsdj}t|jddxsdj}|jr2|r0|dk7r+tj j |j||Stj j |j|S)Nr unknownr r)r+r,r%rr1r rfrQ)rarr r s rA_skill_dir_pathzSkillManager._skill_dir_pathSs599VY/<9=CCEuyyY7D9EKKM  % % 'HY9N77<< 0 0(DA Aww||D,,d33rdc`tjj|j|dS)Nr)r1r rfr)rars rA_skill_md_pathzSkillManager._skill_md_pathZs"ww||D007DDrdc.|j|j|_|j|_|j |_d|_|jdk(r|jtjd|jy)zARe-scan the skills directory and rebuild the internal skill bank.NrKz&[SkillManager] reloaded skills from %s) rurVrWrXrYrZr[rTrGr`r!r^rQrgs rAreloadzSkillManager.reload]sv '') #'#C#C#E &&( '+$   + -  * * , N>NOrdc|j}||jk(ry|j|xjdz c_tj dy)z>Reload skills if the on-disk skill library changed externally.Frz>[SkillManager] detected local skill changes; refreshed libraryT)rXrYrrUr!r^)racurrents rArefresh_if_changedzSkillManager.refresh_if_changedhsH224 d.. .  1 TUrdc|j> ddlm}tj d|j ||j |_|jS#t$r tdwxYw)Nr)SentenceTransformerzjsentence-transformers is required for embedding retrieval. Install with: pip install sentence-transformersz*[SkillManager] loading embedding model: %s)rSsentence_transformersr ImportErrorr!r^rH)rars rA_get_embedding_modelz!SkillManager._get_embedding_modelvsp  ( E KKDdF_F_ `$78Q8Q$RD !$$$ !F s AA,c|jddj|jddjg}|jddj}|r|j|dddjd|DS)Nr rr rz. c3&K|] }|s| ywr).0ps rA z.SkillManager._skill_to_text..s/qQ/s)r,r%rrf)rpartsrs rA_skill_to_textzSkillManager._skill_to_texts~ IIfb ! ' ' ) IImR ( . . 0 ))Ir*002  LL# 'yy/E///rdc|j |jSddl}t|jj dg}|Dcgc]}|j |}}|s+g|j dtd|_|jS|j}|j|ddd}||d|_tjd t||jScc}w) NrrM)rr)dtype)r3 embeddingsTFnormalize_embeddingsshow_progress_barconvert_to_numpyz)[SkillManager] cached %d skill embeddings) rTnumpylistrWr,rzerosfloatrr/r!r^r_)ranp all_itemsrtextsmodelrs rAr`z&SkillManager._compute_skill_embeddingss  ' ' 3// /r:; 9BC$$U+CC hhvUh;,D (// /))+\\ !%#! " $( $  ?YP++++DsC' similarityc:|j|}|dd|zzzS)zz2SkillManager._embedding_retrieve..s,$..uT!W~uQx||FTV?WXrdkeyreverser)r`rr/rranger_maxr) rarrrr query_embrankedcandidate_indicesrrr3rs ` @@rA_embedding_retrievez SkillManager._embedding_retrieves..0W~I))+LL  !%#! !  \"Y.g #d) X  ##:SE%:;--.?N"&'Qa'''s B.cjdk(rj||Stjj dg}t |fdd}|d|S)aRetrieve relevant skills for *task_description*. In embedding mode, skills are ranked by similarity * effectiveness and deduplicated by embedding similarity. In template mode, all skills are sorted by effectiveness without any category-specific routing. rKrMcFj|jddSr)rr,)sras rArz'SkillManager.retrieve..s$00vr1BCrdTrN)rGrrrWr,r)rarrrMall_skills_sorteds` rAretrievezSkillManager.retrievesc   + -++,Escape XML special characters (matching OpenClaw's escapeXml).&z&z>"z"rLz')replace)rs rA _escape_xmlzSkillManager._escape_xml&sG LLg & WS& ! WS& ! WS( # WS( #  rdrWc |sytj}gd}|D]}|jd|jd||jddd|jd||jddd |jd ||j |xs|jd dd |jd |jddj |S)a5Build the *full* ```` XML catalog. Output matches ``formatSkillsForPrompt`` from ``@mariozechner/pi-coding-agent`` (used by OpenClaw): preamble text followed by ```` with ````, ````, and ```` per skill. r)K The following skills provide specialized instructions for specific tasks.zOUse the read tool to load a skill's file when the task matches its description.When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.r r z r z r  rDr rr,rrfrarWescapelinesrs rAformat_skills_for_promptz%SkillManager.format_skills_for_prompt1s))  'E LL % LL:fUYYvr-B&C%DGL M LL,VEIImR4P-Q,RR`a b LL (?(?(F(d%))T_acJd!e ffqr  LL & '  *+yyrdc |sytj}gd}|D]}|jd|jd||jddd|jd||j |xs|jddd |jd |jd d j |S) zBuild the *compact* ```` XML catalog. Omits ```` to save tokens. Matches OpenClaw's ``formatSkillsCompact``. r)rzHUse the read tool to load a skill's file when the task matches its name.rrrrrr rrrrrrrrrs rAformat_skills_compactz"SkillManager.format_skills_compactPs ))  'E LL % LL:fUYYvr-B&C%DGL M LL (?(?(F(d%))T_acJd!e ffqr  LL &  '  *+yyrd skills_promptread_tool_namec d|j}|sydjddd|dddd d |dg S) zWrap a skills catalog string with the ``## Skills (mandatory)`` instruction block. Matches OpenClaw's ``buildSkillsSection`` in ``system-prompt.ts``. rrz## Skills (mandatory)z?Before replying: scan entries.zN- If exactly one skill clearly applies: read its SKILL.md at with `z`, then follow it.zM- If multiple could apply: choose the most specific one, then read/follow it.z2- If none clearly apply: do not read any SKILL.md.zPConstraints: never read more than one skill up front; only read after selecting.z- When a skill drives external API writes, assume rate limits: prefer fewer larger writes, avoid tight one-item loops, serialize bursts when possible, and respect 429/Retry-After.)r%rf)r!r"trimmeds rAbuild_skills_sectionz!SkillManager.build_skills_sectionls^ %%'yy'Q$$2#33EG_Db/   rd max_charsc|j}|sy|j|}t||kr|}n|j|}|j ||S)a/One-call helper: catalog all skills and wrap with instructions. Uses the full format (name + description + location) when the catalog fits within *max_chars*; falls back to compact format (name + location) otherwise. Returns the empty string when no skills are loaded. r)rrr_r r%)rar&r"rW full_promptcatalogs rAbuild_injection_promptz#SkillManager.build_injection_prompts]$$&33F; { y (!G008G((.AArdr c|jjdgDcgc]}|jd|k7s|c}|jd<ycc}w)z9Remove a skill from in-memory structures (not from disk).rMr Nr)rar rs rA_remove_skill_from_memoryz&SkillManager._remove_skill_from_memorysB04  b0Q$k1UVUZUZ[aUbfjUjQ$k L!$ks AAc0|jddj}|stjdytj |stjd|y|j }||vrP|jdr(|j|tjd|ntjd|y|jDcic]\}}|jd r|d k(s||!}}}d |vr7tj|jjd d |d <d|vr1tj j#|j%||d<t'|jddxsdj|d<|j(j+dgj-|d |_|j1||j3|_tjd|ycc}}w)a Add a new skill to the in-memory bank and write its SKILL.md file. Returns True if the skill was added, False if it already exists (unless ``skill["_replace"]`` is truthy, in which case the old version is overwritten). r rz1[SkillManager] add_skill called with missing nameFz.[SkillManager] rejected invalid skill name: %s_replacez+[SkillManager] replacing existing skill: %sz+[SkillManager] skipping duplicate skill: %s_rrNrrr rrMz[SkillManager] added skill: %sT)r,r%r!r" _SAFE_NAME_REmatch_get_all_skill_namesr,r^r3r#r-r.r/r0r1r r2rr+rWrrrT_write_skill_mdrXrY)rarr existingr>r? clean_skills rA add_skillzSkillManager.add_skillsyy$**, NNN O""4( NNKT R,,. 8 yy$..t4 I4P I4P(- l1Q\\#=NRSWkRkq!tl l { " 't{{} = G G I#2 NK  k )')ww'7'78K8KK8X'YK $"%kooj)&L&YPY"Z"`"`"b J |R077 D'+$ [)#'#C#C#E  4d;ms H;H new_skillsr cd}|D]%}d|vri|d|i}|j|s!|dz }'|dkDr|xjdz c_|S)zAdd multiple skills; returns count actually added. Increments ``self.generation`` when at least one skill is successfully added, signalling callers that the local skill library changed. rr r)r6rU)rar7r addedrs rA add_skillszSkillManager.add_skillssb  E&757*h7~~e$    19 OOq O rdcT g}|jdd}|jdd |jd}|jdi}|jd|t fdd D}|rH jd d jd d jdd}|jd|d n|jd |j D]Q\}}|j drt j||idddj} |j| S|rbt|trRtj|dd} djd| jD} |jd| dj|S)uLSerialize skill frontmatter as YAML, OpenClaw-compatible. Produces output like:: name: my-skill description: "Rich description with: colons and special chars." homepage: https://example.com metadata: { "openclaw": { "emoji": "🔧" }, "skillclaw": { "category": "coding" } } Extra frontmatter fields (``homepage``, ``user-invocable``, etc.) are written between ``description`` and ``metadata`` to match the OpenClaw SKILL.md convention. r rr rr rzname: c3&K|]}|v ywrr)rcr s rArz3SkillManager._format_frontmatter..sMA,Msz:{}[],"'#&*!|>%@` \z\\r z\"rz\nzdescription: "z description: r/FTi')default_flow_style allow_unicodewidthrprqc3&K|] }d|z yw)z Nr)rlns rArz3SkillManager._format_frontmatter.. s Kr Ksz metadata: )r,ranyr r3r#r&rtr%r)r*rkdumpsrf splitlines) rrr r extra_fm needs_quotingescapedrvaluedumpedjson_strindentedr s @rA_format_frontmatterz SkillManager._format_frontmatters&yy+ii r2 99Z(99126 vdV_%M6LMM !))$7??UKSSTXZ_`G LL>'!4 5 LL= 6 7#..* !JC~~c"YYe #("  eg  LL  !  8T2zz(qIHyy KX5H5H5J KKH LL;xj1 2yyrdc$|jdd}|j|}tjj |}|j tjj |j tjzstjd|ytj|d|j|}|jdd}|jd d }t|jd xsi}|r|dk7r||jd id<||jd d d} |jd} | r| | d<|r|| d <|j| } d| d|d} t|dd5} | j!| dddtjj ||d<tj#d|y#1swYBxYw#t$$r!}tjd||Yd}~yd}~wwxYw)aPersist a single skill to its SKILL.md file (AgentSkills / OpenClaw compatible format). Category is stored in ``metadata.skillclaw.category`` (not as a bare top-level frontmatter field) so the output is fully OpenClaw-compatible. Extra frontmatter fields (e.g. ``homepage``) that were parsed from an existing SKILL.md are preserved in the output. r rz7[SkillManager] blocked path traversal in skill name: %sNT)exist_okr rrrr rr )r r rz--- z --- rrorrrz#[SkillManager] wrote skill file: %sz%[SkillManager] could not write %s: %s)r,rr1r r2r#rQsepr!r"makedirsrr*rrNrwriter^r )rarr r canonicalfilepathr rr write_skillrGr9rr5r7s rAr3zSkillManager._write_skill_mdsyy+((/ GG$$Y/ ##BGG$4$4T5E5E$F$OP NNTVZ [  I-&&u-99Z3))Ir* *-34 I-?GH   R 0 < 99]B7' 9912 08K, - &.K #**;7wiy 4 Qhg6 !  !#!1!1(!;E+  KK=x H   Q NNBHa P P Qs18G%GAG%G"G%% H.H  Hr ct|jjdg}|D]}|j||j |_t jdt||jy)z Persist all in-memory skills back to .md files. ``path`` is ignored (kept for backward compatibility); files are always written to skills_dir. rMz$[SkillManager] saved %d skills to %sN) rrWr,r3rXrYr!r^r_rQ)rar rMrs rAsavezSkillManager.save<sf$++//,;<  (E   ' (#'#C#C#E  :C OTM]M]^rdc|jjdgDchc].}|jdst|jd0c}Scc}w)NrMr )rWr,r+rs rAr2z!SkillManager._get_all_skill_namesIsA,0KKOOL",M_qQRQVQVW]Q^AEE&M"___s AAcZtd|jjdgDS)Nc3XK|]"}t|jdxsd$yw)r rN)r+r,)rrs rArz0SkillManager._category_counts..Ms#fqs155,9 :fs(*rM)rrWr,rgs rAr]zSkillManager._category_countsLs$fDKKOOT`bdDefffrdct|jjdgt|j dS)NrM)r by_category)r_rWr,r*r]rgs rAget_skill_countzSkillManager.get_skill_countOs4r:; 5 5 78  rd)rrJN)rN)g?))r)i0ur)rr):__name__ __module__ __qualname____doc__r+rrcrhrrrZrurxrrrrrrrVrrrrXboolrr*rrrrr staticmethodrr`rrrrrrrr rr r%r*r,r6r:rNr3rXsetr2rr]r^rrdrArDrDs "$(.2 '-'-'- '- 'sm '-ZBSB T#tCH~"56 I""DI"$"&"49"U"t" /C/E/!4T#s(^(;#<!d38n"*c*"U5c33G3L-M"  t 4T4c4EDESE PD %0d38n000,4,<.%.S.U. ORCy)-69FK c,(C((T (8))S)d),  T  Dd38n)<$=2GGG # #   tDz c > DJ 3 8%      > $BBB B*lcldl%t%%NT$Z3s 2 42 C2 2 h+QT+Qd+QZ _# _$ _`c`g'g  rdrD)rcrr-rkloggingr1rer collectionsrtypingrrrr& skill_bundler getLoggerr`r!compiler0r4r+rBrDrrdrArns.`   && 1   8 $ 45 @ K#K(4S>":Kfu  u  rd