yj8@ UdZddlmZddlZddlmZddlmZddlm Z m Z m Z m Z ddl mZmZddd d d d d d d d Zd ed<dZdZdZdZdZdZeGddZd9dZd:dZd:dZd:d Zd;d#Zd;d$Zdd)Z#dd*d?d,Z$d@d/Z%dAd1Z&dBd3Z'dCdDd7Z(e)d8krddl*Z*e*j+e(dSdS)EuStructural + convention linter for SKILL.md files. The hard *validator* in ``tools/skill_manager_tool.py::_validate_frontmatter`` guards the non-negotiables (fence present, YAML mapping, ``name`` + ``description`` present, description length, non-empty body, size cap) and is a create/edit BLOCKER. This module is the softer, broader companion: it encodes the "Skill authoring standards (HARDLINE)" conventions from ``CONTRIBUTING.md`` that today are only caught by a human reviewer — shell-utility references instead of native tools, a missing author/license/metadata block, a ``name`` that doesn't match its directory, dangling ``references/`` links, marketing words in the description, ``platforms:`` gating vs POSIX-only primitives, and forbidden scaffolding files. Design contract (matches the Hermes "no lazy-reading escape hatches / don't destroy the feature" posture): * Findings are **advisory** by default. ``lint_skill`` returns a list of :class:`LintFinding`; the caller decides whether any severity blocks. The create-path surfaces them as guidance, never as a hard reject (the hard rejects already live in the validator). * Pure functions, no I/O beyond reading the files it is pointed at, so CI, the ``skill_manage`` create path, and a contributor running it locally all share one implementation. * Reuses ``agent.skill_utils`` helpers rather than re-parsing frontmatter, so BOM handling / platform matching / the 60-char prompt budget stay in one place. ) annotationsN) dataclass)Path)AnyDictListOptional)SKILL_PROMPT_DESC_LIMITparse_frontmatter search_files read_filepatchzsearch_files (target='files')) greprgcatheadtailsedawkfindlszDict[str, str]_SHELL_UTIL_TO_TOOL)powerful comprehensiveseamlessadvancedz cutting-edgezstate-of-the-art revolutionaryrobust)fcntltermiosz os.setsidzsignal.SIGKILL osascriptz/proc/zapt-get systemctl)z README.mdz CHANGELOG.mdz install.shz.envz .env.examplez .gitignore)z When to Usez When to useerrorwarningc:eZdZUdZded<ded<ded<d dZdS) LintFindingzGA single lint result. ``severity`` is advisory metadata for the caller.strseverityrulemessagereturncR|jtkrdnd}|d|jd|jS)Nu✗u⚠z [z] )r(ERRORr)r*)selfbadges 8/home/ragecks/.hermes/hermes-agent/tools/skill_linter.pyformatzLintFinding.formatos7%//U664966 666N)r+r')__name__ __module__ __qualname____doc____annotations__r1r2r0r&r&gsKQQMMM IIILLL777777r2r& frontmatterDict[str, Any] skill_dirOptional[Path]r+List[LintFinding]c |gSt|dd}|sgS||jkr#t t dd|d|jdgSgS)Nnamezname-dir-mismatchzfrontmatter name 'z' does not match directory 'z'; they must be identical.)r'getstripr?r&r-)r9r;r?s r0_check_name_matches_dirrCws {vr** + + 1 1 3 3D   y~ #?T??N???     Ir2ct|dd}|sgStjd|st t dd|dgSgS)Nr?r@z[a-z0-9][a-z0-9_-]*z name-formatzname 'zC' must be lowercase letters, digits, hyphens, and underscores only.)r'rArBre fullmatchr&r-)r9r?s r0_check_name_formatrGs {vr** + + 1 1 3 3D  <. 5 5 ))))     Ir2c g}t|ddd}|s|St|tkrB|t tddt|dtd|fdtD}|r-|t td d |d |S) N descriptionr@z'"zdescription-lengthzdescription is z' chars; the skill index truncates past z? chars + '...', losing routing signal. Keep it to one sentence.cjg|]/}tjdtj|d-|0S)z\b)rEsearchescape).0wlowers r0 z&_check_description..s> T T T!295K29Q<<5K5K5KU+S+S TA T T Tr2zdescription-marketingz%description contains marketing words z'; state the capability, not adjectives.) r'rArBlenr appendr&WARNINGrO_MARKETING_WORDS)r9findingsdeschitsrOs @r0_check_descriptionrXs'"$H {}b11 2 2 8 8 : : @ @ G GD  4yy*** $4#d))44/444      JJLLE T T T T' T T TD   '////      Or2c g}dD]3}||vr-|ttdd|d4|d}t |t r|dnd}t |t s*|ttddn-d|vr)|ttdd t |d d }|r[|d vr3|d kr-|ttdd|d|S)N)versionauthorlicensezmissing-metadatazfrontmatter is missing 'z'; every peer skill has it.metadatahermesz>frontmatter is missing metadata.hermes.{tags, related_skills}.tagsz metadata.hermes.tags is missing.r[r@)r^agentz hermes agentz Hermes Agentz author-capszauthor 'zD' should be 'Hermes Agent' (proper caps) or a real contributor name.) rRr&rSrA isinstancedictr'rBrO)r9rUkeymeta hermes_metar[s r0_check_metadata_blockrfs"$H/ k ! ! OO&OsOOO    ??: & &D(24(>(>H$((8$$$DK k4 ( ( "P        $ $ OO/1S    2.. / /F  &,,..&&((,OOO.   /6///      Or2bodyr'c g}t|}tD]`\}}tjdtj|d|r0|ttdd|d|da|S)zDFlag banned shell utilities named in PROSE (not fenced code blocks).`zshell-utility-referencezprose references `z`; name the native tool `z ` instead.) _strip_code_blocksritemsrErKrLrRr&rS)rgrUproseutiltools r0_check_shell_utilitiesros"$H t $ $E)//11   d 9,")D//,,,e 4 4  OO-))))))    Or2cvtfdtDsttddgSgS)Nc3K|]9}tjdtj|tjV:dS)z^#+\s+N)rErKrLM)rMsrgs r0 z"_check_sections..sD[[1ry129Q<<114>>[[[[[[r2zmissing-sectionzXno '## When to Use' section found; skills need explicit trigger conditions near the top.)any_EXPECTED_SECTIONSr&rSrgs`r0_check_sectionsrxsR [[[[HZ[[[ [ [ !3     Ir2c x|gSg}t}tjd|D]}|d}||vr||d|vs|drK||z s-|ttdd|d|S) z>Flag references/ links in the body that don't resolve on disk.Nz&(references|templates|assets)/[\w./-]+r*/zdangling-referencezbody references 'z6' but that file does not exist in the skill directory.) setrEfinditergroupaddendswithexistsrRr&rS)rgr;rUseenmatchrels r0_check_reference_linksrs "$HUUDFMMkk!nn $;;   #::c**: C''))  OO(////    Or2c|gS|drgS|dz }|sgSi}|dD]h}|r |jdvr |ddn#t $rYEwxYwfd tD}|r |||j<i|rLd d | D}ttd d |dgSgS)zAIf bundled scripts use POSIX-only primitives, require platforms:.N platformsscriptsrz)z.pyz.shz.bashutf-8ignoreencodingerrorscg|]}|v| Sr8r8)rMptexts r0rPz+_check_platforms_gating..6s999QqDyyqyyyr2z; c3*K|]\}}|d|VdS)z: Nr8)rMkvs r0rtz*_check_platforms_gating..:s0EE41aa;;1;;EEEEEEr2zplatforms-gatingz#scripts use POSIX-only primitives (zi) but no 'platforms:' frontmatter is declared. Fix cross-platform or gate with platforms: [linux, macos].) rAis_dirrglobis_filesuffix read_textOSError_POSIX_PRIMITIVESr?joinrkr&rS)r9r; scripts_dir offendersscripthitdetailrs @r0_check_platforms_gatingr#sj {## i'K      &(I##C(( ) )~~ 6=8O#O#O  ##WX#FFDD    H 9999+999  )%(Ifk "  EE9??3D3DEEEEE "8f888     Is0B BBc |gSg}tD]F}||z r-|ttdd|dG|S)Nzforbidden-filez skill ships 'z6'; skills should not include scaffolding/config files.)_FORBIDDEN_FILESrrRr&rS)r;rUfnames r0_check_forbidden_filesrGs "$H!     % % ' '  OO$1E111    Or2c |d}|sgShdt|tr|n|g}fd|D}|r+ttdd|dt dgSgS)Nr>linuxmacosdarwinwindowscZg|]'}t|v%|(Sr8)r'rO)rMrvalids r0rPz._check_platform_list_valid..^s1 ; ; ;s1vv||~~U::1:::r2zplatforms-valuez)platforms contains unrecognized value(s) z; expected a subset of .)rAralistr&rSsorted)r9rrkbadrs @r0_check_platform_list_validrXs ,,I  3 3 3E#It44 EII9+E ; ; ; ;e ; ; ;C  !.C..#E]]...     Ir2cFtjdd|tjS)zFRemove fenced code blocks so prose-only checks don't fire on examples.z ```.*?```r@)flags)rEsubSrws r0rjrjns 6,D 5 5 55r2r;contentct|\}}g}|t|z }|t||z }|t|z }|t |z }|t |z }|t |z }|t|z }|t||z }|t||z }|t|z }|S)uLint raw SKILL.md *content*. Pass ``skill_dir`` to enable on-disk checks (name/dir match, dangling reference links, POSIX-primitive gating, forbidden files). Without it, only content-only checks run — useful for the create path, where the file is not yet written. ) r rGrCrXrfrrorxrrr)rr;r9rgrUs r0 lint_contentrvs*'22K"$H ";///H ' Y???H ";///H %k222H *;777H &t,,,H %%%H &tY777H ' Y???H &y111H Or2 skill_md_pathrczt|}|dd}t||jS)z>Lint a SKILL.md file on disk, with all on-disk checks enabled.rrrr)rrrparent)rrs r0 lint_skillrs=''M%%wx%HHG =+? @ @ @@r2rUc@dd|DS)z9Render findings as a newline-joined human-readable block. c3>K|]}|VdSN)r1rMfs r0rtz"format_findings..s*22AQXXZZ222222r2)rrUs r0format_findingsrs# 9922222 2 22r2boolc4td|DS)Nc36K|]}|jtkVdSr)r(r-rs r0rtzhas_errors..s)55qqzU"555555r2)rurs r0 has_errorsrs 55H555 5 55r2argvOptional[List[str]]intc8ddl}||n|jdd}|stddSg}|D]}t|}|r6|t |d[|jdkr*| r| |td|d}d}|D]s}t|} | s|t| z }t| rd }td |jjd |d tt| t|dkr!td t|dn#td |dt|d|rdndS)a`CLI: ``python -m tools.skill_linter ...`` Accepts SKILL.md files or skill directories (recursively linted). Prints findings grouped per skill. Exit code 1 if any ERROR-severity finding is present (WARNING-only is exit 0), so CI can gate on structural breakage without failing on advisory convention nits. rNz>usage: python -m tools.skill_linter ...zSKILL.mdzskip (not a SKILL.md or dir): FTrz (z):zAll z skill(s) clean.z finding(s) across z skill(s).)sysrprintrrextendrrr?rrRrrQrrr) rrargstargetsargr any_errortotalskill_mdrUs r0_mainrsJJJ#44!""D  NOOOqG:: II 88:: : NN6!''*"5"566 7 7 7 7 Vz ! !aiikk ! NN1     8388 9 9 9 9I E))h''   X h   I 78?'778777888 oh''(((( zz 3S\\3334444 E5EES\\EEEFFF 11q r2__main__)r9r:r;r<r+r=)r9r:r+r=)rgr'r+r=)rgr'r;r<r+r=)r;r<r+r=)rgr'r+r')rr'r;r<r+r=)rrr+r=)rUr=r+r')rUr=r+rr)rrr+r),r6 __future__rrE dataclassesrpathlibrtypingrrrr agent.skill_utilsr r rr7rTrrrvr-rSr&rCrGrXrfrorxrrrrrjrrrrrr3rexitr8r2r0rs8#""""" !!!!!!,,,,,,,,,,,,        + ) ' '      4   7 7 7 7 7 7 7  7(     @((((V&    :!!!!H",6666262AAAA3333 6666)!)!)!)!)!X zJJJ CHUUWWr2