{"id":"0f20c4d4-10c9-4178-b961-0b9c6751c3e1","entityType":"agent","slug":"clawhub-airscripts-agentskill","name":"Agentskill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-airscripts-agentskill","canonicalPath":"/agent/clawhub-airscripts-agentskill","generatedAt":"2026-10-11T10:49:24.604Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":null},"description":"Let any agent produce code indistinguishable from the existing codebase.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17f2vd423cnfs44ybpyjk4zv585kxfb:agentskill","sourceUrl":"https://clawhub.ai/airscripts/agentskill","homepage":"https://clawhub.ai/airscripts/skills/agentskill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/airscripts/agentskill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/airscripts/skills/agentskill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Agentskill technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":null},"stars":null,"forks":null,"downloads":1122,"packageName":null,"latestVersion":"1.4.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:40:09.374Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T07:40:09.389Z","lastCrawledAt":"2026-10-11T07:40:09.374Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T07:40:09.374Z","lastVerifiedAt":null,"highlights":[{"version":"1.4.0","createdAt":"2026-05-06T23:16:37.554Z","changelog":"Agentskill 1.4.0 - Added explicit distinction between AI-led (skill) and CLI static (operator) generation for AGENTS.md. - Clarified that in skill mode, only analyzer commands are used for evidence; final document is always authored by the AI, not by static CLI generation. - Updated operational rules and workflow to emphasize evidence gathering vs. authorship responsibilities. - Expanded SKILL.md to document both modes and enforce correct usage in AI-assisted workflows. - No breaking changes to workflow steps or trigger phrases.","fileCount":119,"zipByteSize":202514},{"version":"1.3.0","createdAt":"2026-05-02T23:28:12.527Z","changelog":"Agentskill 1.3.0 - Added new scripts: `scripts/analyze.py`, `scripts/generate.py`, and `scripts/update.py`. - Expanded skill capabilities for analysis, generation, and updating routines through these new support scripts. - No changes to core workflow or operational spec in SKILL.md.","fileCount":49,"zipByteSize":98629},{"version":"1.2.0","createdAt":"2026-05-02T23:02:41.099Z","changelog":"Agentskill 1.2.0 - Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, README and PROJECT ROADMAP. - Added PLANNER.md to outline planning practices. - Added SECURITY.md with security guidelines. - Introduced OWNERS file for maintainership. - Provided a dedicated skill icon (assets/agentskill.png). - Initial VERSION file established for release tracking.","fileCount":46,"zipByteSize":97451},{"version":"1.1.0","createdAt":"2026-05-02T22:36:45.167Z","changelog":"Agentskill 1.1.0 - Enhanced the synthesis step to clarify that qualitative sections (naming, imports, error handling, comments, testing) must draw directly from concrete source evidence and real code snippets, using analyzer output for file selection only. - No code or script changes; documentation and workflow remain the same except for this clarification in SKILL.md. - Ensures style guidance in AGENTS.md is based on static evidence from the codebase, reinforcing forensic accuracy.","fileCount":110,"zipByteSize":180163},{"version":"1.0.0","createdAt":"2026-05-02T14:56:47.402Z","changelog":"Agentskill 1.0.0 - Initial stable release. - Added operational spec for extracting coding conventions and synthesizing an AGENTS.md from one or more code repositories. - Includes detailed step-by-step workflow, script invocation guidance, and fallback/uncertainty handling. - Provides documentation and reference files, including CLI and command references. - Introduced tests covering CLI contract, documentation, and language support matrix.","fileCount":110,"zipByteSize":173390},{"version":"0.10.0","createdAt":"2026-04-30T15:22:54.502Z","changelog":"Agentskill 0.10.0 - All code and submodules previously under `scripts/` moved to the new `agentskill/` package. - Corresponding updates to module paths and imports throughout the skill. - No changes to operational logic or feature set. - Updated SKILL.md to reflect current operational rules and workflow; no functional changes.","fileCount":102,"zipByteSize":162134},{"version":"0.9.0","createdAt":"2026-04-29T23:33:20.675Z","changelog":"Agentskill 0.9.0 - Launched foundational library scripts for runners, output schema, and reference flows. - Added contract-driven and schema-based tests for core functionality. - Introduced multiple sample contract/config files for complex agent behavioral scenarios. - Enhanced SKILL.md with explicit fallback/availability rules for example consultation. - Ensures robust extraction, measurement, and configuration logic for AGENTS.md synthesis.","fileCount":101,"zipByteSize":159945},{"version":"0.8.0","createdAt":"2026-04-29T22:25:05.214Z","changelog":"Agentskill 0.8.0 - Added CLI entrypoint script: `scripts/lib/cli_entrypoint.py`. - Introduced tests for CLI entrypoint: `tests/test_cli_entrypoint.py`. - Added tests for error handling contracts: `tests/test_error_contracts.py`.","fileCount":86,"zipByteSize":144830}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f2vd423cnfs44ybpyjk4zv585kxfb:agentskill","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17f2vd423cnfs44ybpyjk4zv585kxfb:agentskill` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/airscripts/agentskill before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T10:49:24.597Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-airscripts-agentskill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":null},"readme":"Skill: Agentskill\n\nOwner: airscripts\n\nSummary: Let any agent produce code indistinguishable from the existing codebase.\n\nTags: latest:1.4.0\n\nVersion history:\n\nv1.4.0 | 2026-05-06T23:16:37.554Z | user\n\nAgentskill 1.4.0\n\n- Added explicit distinction between AI-led (skill) and CLI static (operator) generation for AGENTS.md.\n- Clarified that in skill mode, only analyzer commands are used for evidence; final document is always authored by the AI, not by static CLI generation.\n- Updated operational rules and workflow to emphasize evidence gathering vs. authorship responsibilities.\n- Expanded SKILL.md to document both modes and enforce correct usage in AI-assisted workflows.\n- No breaking changes to workflow steps or trigger phrases.\n\nv1.3.0 | 2026-05-02T23:28:12.527Z | user\n\nAgentskill 1.3.0\n\n- Added new scripts: `scripts/analyze.py`, `scripts/generate.py`, and `scripts/update.py`.\n- Expanded skill capabilities for analysis, generation, and updating routines through these new support scripts.\n- No changes to core workflow or operational spec in SKILL.md.\n\nv1.2.0 | 2026-05-02T23:02:41.099Z | user\n\nAgentskill 1.2.0\n\n- Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, README and PROJECT ROADMAP.\n- Added PLANNER.md to outline planning practices.\n- Added SECURITY.md with security guidelines.\n- Introduced OWNERS file for maintainership.\n- Provided a dedicated skill icon (assets/agentskill.png).\n- Initial VERSION file established for release tracking.\n\nv1.1.0 | 2026-05-02T22:36:45.167Z | user\n\nAgentskill 1.1.0\n\n- Enhanced the synthesis step to clarify that qualitative sections (naming, imports, error handling, comments, testing) must draw directly from concrete source evidence and real code snippets, using analyzer output for file selection only.\n- No code or script changes; documentation and workflow remain the same except for this clarification in SKILL.md.\n- Ensures style guidance in AGENTS.md is based on static evidence from the codebase, reinforcing forensic accuracy.\n\nv1.0.0 | 2026-05-02T14:56:47.402Z | user\n\nAgentskill 1.0.0\n\n- Initial stable release.\n- Added operational spec for extracting coding conventions and synthesizing an AGENTS.md from one or more code repositories.\n- Includes detailed step-by-step workflow, script invocation guidance, and fallback/uncertainty handling.\n- Provides documentation and reference files, including CLI and command references.\n- Introduced tests covering CLI contract, documentation, and language support matrix.\n\nv0.10.0 | 2026-04-30T15:22:54.502Z | user\n\nAgentskill 0.10.0\n\n- All code and submodules previously under `scripts/` moved to the new `agentskill/` package.\n- Corresponding updates to module paths and imports throughout the skill.\n- No changes to operational logic or feature set.\n- Updated SKILL.md to reflect current operational rules and workflow; no functional changes.\n\nv0.9.0 | 2026-04-29T23:33:20.675Z | user\n\nAgentskill 0.9.0\n\n- Launched foundational library scripts for runners, output schema, and reference flows.\n- Added contract-driven and schema-based tests for core functionality.\n- Introduced multiple sample contract/config files for complex agent behavioral scenarios.\n- Enhanced SKILL.md with explicit fallback/availability rules for example consultation.\n- Ensures robust extraction, measurement, and configuration logic for AGENTS.md synthesis.\n\nv0.8.0 | 2026-04-29T22:25:05.214Z | user\n\nAgentskill 0.8.0\n\n- Added CLI entrypoint script: `scripts/lib/cli_entrypoint.py`.\n- Introduced tests for CLI entrypoint: `tests/test_cli_entrypoint.py`.\n- Added tests for error handling contracts: `tests/test_error_contracts.py`.\n\nv0.7.1 | 2026-04-29T22:12:09.832Z | user\n\nAgentskill 0.8.0\n\n- Added CLI entrypoint script: `scripts/lib/cli_entrypoint.py`.\n- Introduced tests for CLI entrypoint: `tests/test_cli_entrypoint.py`.\n- Added tests for error handling contracts: `tests/test_error_contracts.py`.\n\nv0.7.0 | 2026-04-29T22:09:26.045Z | user\n\nAgentskill 0.7.0\n\n- Added automation scripts for AGENTS.md update and merge workflows.\n- Introduced feedback update logic and runner support scripts.\n- Developed agents_document.py library for document synthesis.\n- Created comprehensive test suite covering agents document creation, CLI update flow, e2e execution, feedback handling, and merge scenarios.\n- No changes to the SKILL.md workflow or operational spec.\n\nv0.6.0 | 2026-04-29T22:01:10.720Z | user\n\nAgentskill 0.6.0\n\n- Added comprehensive multi-language examples in the `examples/` directory (Bash, C, C++, C#, Go, Java, and JavaScript) with scripts, source code, and tests.\n- Introduced documentation and reference files for each language and framework to guide usage and testing (e.g., Makefiles, CMakeLists.txt, project manifests).\n- Expanded test coverage with representative test files for each language.\n- No changes to operational logic; core workflow and spec remain unchanged.\n\nv0.5.0 | 2026-04-29T21:57:37.873Z | user\n\nAgentskill 0.5.0\n\n- Introduced reference extraction library in `scripts/lib/` with initial modules for adaptation, initialization, and question synthesis.\n- Added comprehensive testing for each new reference module in `tests/`.\n- No changes made to the operational or behavioral specification (`SKILL.md` and supporting files remain unchanged in workflow or instructions).\n- This version lays groundwork for a more modular and testable reference-handling subsystem.\n\nv0.4.0 | 2026-04-29T21:55:00.891Z | user\n\nAgentskill 0.4.0\n\n- Added parsers library to `scripts/lib/` for reusable config file parsing.\n- Introduced fixtures for GolangCI, ESLint, Prettier, Python (pyproject.toml), and Rust (clippy and rustfmt) to aid parser testing.\n- Added comprehensive test suite for config parsers under `tests/test_parsers.py`.\n- Expanded test fixture coverage to support multi-language repository scenarios.\n\nv0.3.0 | 2026-04-29T21:39:46.367Z | user\n\nagentskill 0.3.0\n\n- Added new utility module: scripts/lib/logging_utils.py.\n- Prepares groundwork for improved logging and script maintainability.\n\nv0.2.0 | 2026-04-29T21:34:52.411Z | user\n\nAgentskill 0.2.0\n\n- Added initial workflow and operational specification in `SKILL.md`.\n- Introduced 11 core files, including GitHub Actions workflows, pre-commit configuration, LICENSE, and ROADMAP.\n- Provided a detailed, step-by-step process for analyzing repositories and generating precise `AGENTS.md` files.\n- Established scripts directory (`scripts/common/walk.py`) and placeholders for specs and editor settings.\n- Designed robust fallback and uncertainty handling procedures for extraction failures.\n\nv0.1.0 | 2026-04-26T01:18:44.003Z | user\n\nAgentskill 0.1.0\n\n- Initial release with a detailed operational specification in SKILL.md.\n- Defines explicit workflow for extracting repo conventions and generating AGENTS.md.\n- Lists exact trigger phrases for skill invocation; excludes general code review tasks.\n- Outlines a 10-step process covering repo scanning, metric measurement, config extraction, file reading, and synthesis.\n- Includes fallback procedures for tool/script failures and handling uncertainty.\n- Details integration and precedence rules between SKILL.md and SYSTEM.md.\n\nArchive index:\n\nArchive v1.4.0: 119 files, 202514 bytes\n\nFiles: AGENTS.md (19884b), agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (20065b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan.py (3823b), agentskill/commands/symbols.py (38076b), agentskill/commands/tests.py (48210b), agentskill/common/__init__.py (56b), agentskill/common/constants.py (736b), agentskill/common/fs.py (944b), agentskill/common/languages.py (8064b), agentskill/common/walk.py (1764b), agentskill/lib/__init__.py (63b), agentskill/lib/agents_document.py (4904b), agentskill/lib/cli_entrypoint.py (990b), agentskill/lib/generate_runner.py (9858b), agentskill/lib/interactive_runner.py (5621b), agentskill/lib/logging_utils.py (808b), agentskill/lib/multifile_output.py (4067b), agentskill/lib/output_layouts.py (755b), agentskill/lib/output_profiles.py (633b), agentskill/lib/output_schema.py (3533b), agentskill/lib/output.py (1829b), agentskill/lib/parsers.py (2381b), agentskill/lib/profile_rendering.py (2908b), agentskill/lib/reference_adaptation.py (10884b), agentskill/lib/reference_flow.py (2127b), agentskill/lib/reference_initialization.py (3403b), agentskill/lib/reference_questions.py (14787b), agentskill/lib/references.py (6923b), agentskill/lib/runner.py (4059b), agentskill/lib/update_feedback.py (4099b), agentskill/lib/update_merge.py (6408b), agentskill/lib/update_runner.py (38619b), agentskill/main.py (8301b), CHANGELOG.md (17241b), docs/reference/cli.md (3895b), docs/reference/commands.md (2204b), docs/reference/common.md (1488b), docs/reference/library.md (4006b), docs/reference/README.md (934b), pyproject.toml (1395b), README.md (24429b), references/GOTCHAS.md (8849b), scripts/analyze.py (293b), scripts/config.py (278b), scripts/generate.py (294b), scripts/git.py (275b), scripts/graph.py (277b), scripts/measure.py (279b), scripts/scan.py (276b), scripts/symbols.py (279b), scripts/tests.py (277b), scripts/update.py (292b), skill-card.md (2420b), SKILL.md (20139b), SYSTEM.md (19373b), tests/conftest.py (152b), tests/contract_utils.py (1122b), tests/contracts/analyze_mixed.json (6705b), tests/contracts/analyze_python.json (3964b), tests/contracts/config_mixed.json (267b), tests/contracts/graph_mixed.json (670b), tests/contracts/scan_python.json (436b), tests/contracts/symbols_python.json (937b), tests/fixtures/go/golangci.yml (283b), tests/fixtures/js/eslint.yaml (205b), tests/fixtures/js/prettier.yaml (57b), tests/fixtures/python/pyproject.toml (479b), tests/fixtures/rust/clippy.toml (113b), tests/fixtures/rust/rustfmt.toml (147b), tests/test_agents_document.py (3857b), tests/test_cli_contract.py (10970b), tests/test_cli_entrypoint.py (2164b), tests/test_cli.py (2818b), tests/test_common.py (3304b), tests/test_config.py (17173b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: agentskill\ndescription: Let any agent produce code indistinguishable from the existing codebase.\n---\n\n# SKILL.md — agentskill\n\n> **Operational spec for agentskill.**\n> This file governs _when_ to invoke, _what_ to run, and _in what order_.\n> For _how_ to generate `AGENTS.md`, read [`SYSTEM.md`](./SYSTEM.md) — it is the behavioral bible.\n> These two files are complementary. Neither is sufficient alone.\n\n---\n\n## Purpose\n\nAnalyze one or more code repositories. Extract exact coding conventions. Synthesize a precise, forensic `AGENTS.md` that allows any agent to produce code indistinguishable from the existing codebase.\n\n---\n\n## Generation Modes\n\nagentskill supports two generation modes. The mode determines who authors the\nfinal document:\n\n### AI-led generation (skill mode — this file)\n\nThe model synthesizes the final `AGENTS.md` itself. CLI analyzer commands are\nused **only for evidence gathering** — to extract repository facts that the\nmodel cannot derive reliably from reading source files alone.\n\n**In skill mode, never call `agentskill generate` to produce the final\n`AGENTS.md`.** The model is the author. Analyzer output is the raw material,\nnot the finished product.\n\n### CLI static generation (operator mode)\n\nThe user runs `agentskill generate` directly. The packaged runtime emits\nmarkdown automatically. This is appropriate for deterministic direct generation\nwithout an LLM in the loop.\n\n**Use CLI generation only in non-LLM static/operator workflows where the user\nexplicitly wants tool-generated markdown rather than AI-authored synthesis.**\n\n---\n\n## Rule: AI Authorship\n\n> **The model authors the final document in skill mode.**\n\n- Do not use `agentskill generate` or `python scripts/generate.py` to produce\n the final `AGENTS.md` when operating as a skill or in any AI-assisted\n workflow.\n- Use analyzer commands (`analyze`, `scan`, `measure`, `config`, `git`, `graph`,\n `symbols`, `tests`) to gather repository facts.\n- The final generated markdown must be synthesized by the AI from analyzer\n evidence, direct source file reads, and supporting documentation.\n- Treat analyzer outputs as evidence, not as the final authored document.\n\n---\n\n## Trigger Phrases\n\nInvoke this skill when the user says any of the following — or a close paraphrase:\n\n- _\"Generate an AGENTS.md\"_\n- _\"Extract my coding style\"_\n- _\"Analyze my repo for conventions\"_\n- _\"Create a style guide from my code\"_\n- _\"Update my AGENTS.md\"_\n- _\"My agent doesn't write code the way I do — fix it\"_\n\nDo **not** invoke this skill for general code review, refactoring, or style advice not tied to generating `AGENTS.md`.\n\n---\n\n## File Ecosystem\n\n| File | Role |\n| ------------------------ | -------------------------------------------------------------------------------------- |\n| `SKILL.md` _(this file)_ | Operational spec: workflow, scripts, fallbacks, uncertainty handling |\n| `SYSTEM.md` | Behavioral spec: what to generate, section by section, and how to evaluate it |\n| `references/GOTCHAS.md` | Extraction errors to avoid; update this file whenever a new failure mode is discovered |\n| `examples/` | Analyzer fixtures plus reference `AGENTS.md` examples; consult when handling an unfamiliar repo shape |\n\n> **Maintenance rule:** If SYSTEM.md and SKILL.md ever contradict each other, SYSTEM.md wins. Fix SKILL.md to match.\n\n> **Availability rule:** If this skill was downloaded from ClawHub, or if `examples/` is unavailable locally, do not consult `examples/`; skip it to avoid execution errors.\n\n---\n\n## Workflow\n\nExecute these steps **in order**. Do not skip steps. Do not reorder steps.\n\n---\n\n### Step 1 — Collect\n\nAsk the user for repo path(s). Accept one or more. Confirm before proceeding.\n\n```\nProvide the path(s) to your repository or repositories.\nOne path per repo. Multiple repos are supported.\n```\n\nIf the user provides a monorepo, note this explicitly — steps 3 and 4 of SYSTEM.md apply.\n\n---\n\n### Step 2 — Scan\n\nRun the scan script to get the directory tree and source file inventory.\n\n```bash\npython scripts/scan.py \n```\n\n**Outputs:** annotated directory tree, source files grouped by language with line counts.\n\n**Use the output to decide what to read** — largest files first, entry points and core modules before tests.\n\n> **If the script fails:** Manually walk the directory tree using available file tools. Note in your working context that the scan was manual — this affects reliability of the file inventory for large repos.\n\n---\n\n### Step 3 — Measure\n\nRun the measurement script to get exact formatting metrics.\n\n```bash\npython scripts/measure.py \npython scripts/measure.py --lang python # single language\n```\n\n**Outputs:** per-language indentation unit and size, line length percentiles (p95 and p99), blank line distributions between top-level definitions and between methods, trailing newline convention.\n\n> **If the script fails:** Proceed without exact measurements. Mark all formatting measurements in the generated `AGENTS.md` as `[tentative]` and note that manual inspection was used. Do not estimate percentiles — state the observable range instead.\n\n---\n\n### Step 4 — Config\n\nRun the config script to detect formatters, linters, and their exact settings.\n\n```bash\npython scripts/config.py \n```\n\n**Outputs:** per-language tool detection with relevant config excerpts — `[tool.black]`, `[tool.ruff]`, `[tool.mypy]`, `tsconfig.json`, `.prettierrc`, `.editorconfig`, and equivalents.\n\n> **If the script fails:** Read config files directly from disk. Prioritize: `pyproject.toml`, `package.json`, `.editorconfig`, any `.*rc` files at the repo root. Do not guess what a formatter enforces — only document what you can read from config.\n\n---\n\n### Step 5 — Read SYSTEM.md\n\n**Read [`SYSTEM.md`](./SYSTEM.md) fully before writing a single line of `AGENTS.md`.**\n\nDo not rely on memory of previous runs. Read it fresh every time.\n\n---\n\n### Step 6 — Read Source Files\n\nRead actual source files directly. Use the file inventory from Step 2 to choose what to read.\n\n**Minimum per language before drafting any section:**\n\n| Priority | What to read |\n| -------- | ----------------------------------------------------------------------- |\n| 1st | Entry point and CLI files |\n| 2nd | Core logic modules (largest non-test files) |\n| 3rd | At least one test file |\n| 4th | Package manifest (`pyproject.toml`, `Cargo.toml`, `package.json`, etc.) |\n| 5th | At least one utility or helper module |\n\n**Minimum count:** 3–5 files per language. For monorepos, 3–5 files per service.\n\nDo not begin drafting until this step is complete.\n\n---\n\n### Step 7 — Check GOTCHAS.md\n\nRead [`references/GOTCHAS.md`](./references/GOTCHAS.md) before drafting.\n\nThis file contains extraction and synthesis errors discovered from previous agentskill runs — false patterns, formatter assumption traps, monorepo boundary mistakes, and section omissions.\n\n---\n\n### Step 8 — Consult Examples\n\nRead the relevant file in [`examples/`](./examples/) if you are handling an unfamiliar repo shape.\n\nIf this skill was downloaded from ClawHub, or if `examples/` is unavailable locally, skip this step to avoid execution errors.\n\n| Scenario | File to consult |\n| ------------------------------- | ----------------------------- |\n| Standard single-language repo | `examples/SINGLE_LANGUAGE.md` |\n| Monorepo with multiple services | `examples/MONOREPO.md` |\n| Multi-language single repo | `examples/MULTI_LANGUAGE.md` |\n\n> **If no relevant example exists:** Proceed without one. Do not consult an example from a different repo shape — it will introduce structural assumptions that don't apply.\n\n---\n\n### Step 9 — Choose Output Shape\n\nBefore generating, determine the output profile and layout. Skip this step only\nif the user has already specified both preferences.\n\n**Profile** controls content density:\n\n| Profile | Description |\n| --------------- | -------------------------------------------------------- |\n| `concise` | Shorter, high-signal operational guidance only |\n| `comprehensive` | Full detail with representative snippets and expanded rationale |\n\n**Layout** controls output packaging:\n\n| Layout | Description |\n| ----------- | ------------------------------------------------------------------------- |\n| `single` | One complete markdown file (default) |\n| `split` | Concise primary file plus comprehensive companion reference doc |\n| `multifile` | Root index file plus one markdown file per section in a `.agentskill/` dir |\n\n**Asking the user:**\n\nIf generation intent is clear but neither profile nor layout has been specified,\nask the user briefly:\n\n```\nWhich output shape do you want?\nProfile: concise or comprehensive\nLayout: single file, split, or multifile\n```\n\n**Handling partial or delegated preference:**\n\n| User response | Action |\n| ---------------------------------------- | ------------------------------------------------------- |\n| Both profile and layout specified | Use their choices; do not ask again |\n| One specified, the other missing | Ask only for the missing choice |\n| \"default\" or \"whatever is best\" | Use profile `concise` and layout `single` |\n| Only layout chosen | Use profile `concise` unless layout is `multifile`, then use profile `comprehensive` |\n\n**Important:** Do not silently choose `split` or `multifile` when the user has\nnot requested a multi-document layout. These layouts produce multiple files and\nchange how the output is consumed — the user must opt in explicitly.\n\n**For update workflows:** Only `single` layout is supported. If the user\nrequests `split` or `multifile` layout for an update, explain that only single\nlayout is currently supported for updates, then proceed with `single`.\n\nAfter selection, confirm the chosen shape in one line before proceeding:\n\n```\nGenerating: profile=concise, layout=single\n```\n\n---\n\n### Step 10 — Synthesize\n\nFollow SYSTEM.md **section by section**, in the exact order specified.\n\n**You are the author.** Do not delegate final generation to `agentskill generate`.\nCompose each section from the evidence gathered in Steps 2–8 and the source\nreads in Step 6.\n\n**Source of truth per data type:**\n\n| Data type | Source |\n| ------------------------------------------- | -------------------------------------- |\n| Line length, indentation, blank line counts | Script output from Step 3 |\n| Formatter and linter settings | Script output from Step 4 |\n| Naming conventions | Direct source file reads (Step 6) |\n| Error handling patterns | Direct source file reads (Step 6) |\n| Import ordering | Direct source file reads (Step 6) |\n| Comment and docstring style | Direct source file reads (Step 6) |\n| Test patterns | Direct source file reads (Step 6) |\n| Directory structure | Script output from Step 2 |\n| Git conventions | `.git/` config + commit log inspection |\n\nFor qualitative sections such as naming, imports, error handling, comments, and testing, enrich from static source evidence first: concrete rules plus real snippets. Use analyzer output to find candidate files, not as the section body.\n\nApply the **Mimicry Test** from SYSTEM.md to each section before moving to the next. Do not batch-test at the end.\n\n---\n\n### Step 11 — Handle Uncertainty\n\nWhen you are uncertain about a pattern mid-synthesis, apply this decision tree — do not silently guess:\n\n```\nIs the pattern supported by fewer than 3 examples?\n YES → Mark the rule [tentative] and continue.\n\nIs there genuine inconsistency with no dominant pattern?\n YES → State the inconsistency explicitly. Do not invent a rule.\n\nIs an entire section unmeasurable (e.g. script failed, files unreadable)?\n YES → Surface this to the user before writing that section.\n Ask: \"I couldn't reliably extract [section].\n Do you want me to skip it, mark it tentative, or provide the data manually?\"\n\nIs the uncertainty minor and isolated to one sub-rule?\n YES → Mark [tentative], continue, note it in the draft summary.\n```\n\n**Never silently guess. Never invent a rule. Never omit a section without telling the user.**\n\n---\n\n### Step 12 — Write\n\nWrite the output according to the layout chosen in Step 9.\n\n**Layout: `single`** — Write one `AGENTS.md` file.\n\n**Layout: `split`** — Write two files:\n- `AGENTS.md` — concise primary with a link to the companion\n- `AGENTS.reference.md` — comprehensive companion reference\n\n**Layout: `multifile`** — Write a root index plus per-section files:\n- `AGENTS.md` — root index with section links\n- `.agentskill/01_OVERVIEW.md`, `.agentskill/02_REPOSITORY_STRUCTURE.md`, ... — one file per section, each with a backlink to the root\n\n**If this is a new file:** Write directly.\n\n**If an existing `AGENTS.md` is present:**\n\n1. Read the existing file first.\n2. Present a diff-style summary of what will change and why.\n3. Ask for confirmation before overwriting.\n\nAfter writing, output a brief summary:\n\n```\nAGENTS.md written.\nProfile: concise | Layout: single\n\nSections completed: 15 / 15\nTentative rules: [list them, or \"none\"]\nSections with gaps: [list them, or \"none\"]\nRecommended follow-up: [e.g. \"Run measure.py — line length marked tentative\"]\n```\n\n---\n\n## Why Seven Scripts?\n\nThe scripts handle exactly and only what an LLM cannot do reliably from reading source files.\n\n| Script | Why it cannot be skipped |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `scan.py` | Large repos exceed the context window; without a file inventory the agent reads arbitrarily, missing dominant patterns in unread files |\n| `measure.py` | 95th-percentile line length requires counting every line across every file — estimation from reading samples is structurally inaccurate |\n| `config.py` | Formatter config files are ground truth; inferring what a formatter enforces from its output is unreliable and will drift as config changes |\n| `git.py` | Commit log and branch history require `git log` access; source files alone do not reveal prefix conventions or merge strategy |\n| `graph.py` | Import graph cycle detection and monorepo boundary identification require traversing all files simultaneously, not reading them one by one |\n| `symbols.py` | Codebase-specific affix detection requires counting patterns across every identifier in the repo — impractical to do by reading samples |\n| `tests.py` | Test-to-source mapping and framework detection require walking the full file tree; sampling misses coverage gaps and naming inconsistencies |\n\nEverything else — error handling patterns, comment style, docstring format, architectural rules — comes from reading source files directly. Do not run scripts for things you can read.\n\n---\n\n## Scripts Quick Reference\n\nAll scripts require Python stdlib only. No installation needed beyond `pip install -e .`.\n\n**Analyzer scripts (for evidence gathering in skill mode):**\n\n```bash\n# Aggregate analyzer wrapper\npython scripts/analyze.py \n\n# Directory tree and file inventory\npython scripts/scan.py \n\n# Formatting metrics (indentation, line length, blank lines, newlines)\npython scripts/measure.py \npython scripts/measure.py --lang python\n\n# Formatter and linter detection with config excerpts\npython scripts/config.py \n\n# Commit log, branch naming, and merge strategy\npython scripts/git.py \n\n# Internal import graph, cycle detection, monorepo boundaries\npython scripts/graph.py \n\n# Symbol name extraction and codebase-specific affix detection\npython scripts/symbols.py \n\n# Test-to-source mapping, framework detection, fixture extraction\npython scripts/tests.py \n\n# Run all seven analyzers in parallel and merge output\nagentskill analyze --pretty\n```\n\n**CLI generation (for operator/static use only, not for skill mode):**\n\n```bash\n# Direct static generation — do not use in skill/AI workflows\nagentskill generate \nagentskill generate --profile comprehensive\nagentskill generate --layout split --out AGENTS.md\nagentskill generate --layout multifile --out AGENTS.md\n\n# Update or create AGENTS.md in place (only layout=single supported)\nagentskill update --profile comprehensive\n```\n\nAnalyzer scripts output JSON to stdout. Pass `--pretty` for human-readable output. Pass `--out ` to write to disk.\n\n> **Boundary rule:** In skill mode, the generate and update commands are\n> available for the user's direct CLI use only. The model must not call them\n> to produce the final `AGENTS.md`.\n\n---\n\n## Uncertainty Reference\n\n| Situation | Action |\n| ------------------------------------------ | ------------------------------------------------------------------------- |\n| Fewer than 3 examples for a rule | Mark `[tentative]` |\n| Genuine inconsistency, no dominant pattern | State the inconsistency; do not invent a rule |\n| Script failed, measurement unavailable | Mark affected measurements `[tentative]`; note manual inspection was used |\n| Entire section unmeasurable | Surface to user; ask before proceeding |\n| Existing `AGENTS.md` present | Diff and confirm before overwriting |\n| No matching example in `examples/` | Skip Step 8; do not use a mismatched example |\n| User requests update with split/multifile | Explain only single layout is supported for updates; proceed with single |\n\n---\n\n## Principles\n\n> These are reminders, not the full spec. The full spec is in SYSTEM.md.\n\n- **Extract, don't guess.** Every rule must be grounded in observed code.\n- **Snippets are the spec.** Every non-trivial rule needs a real code snippet.\n- **Static enrichment beats metric summaries.** Qualitative sections should read like observed code behavior, not analyzer tallies.\n- **3 examples minimum.** Fewer → `[tentative]`. Inconsistency → state it.\n- **Scope every rule.** Repo-wide vs. per-language vs. per-service — always explicit.\n- **No statistics in output.** No counts, percentages, or confidence levels in `AGENTS.md`.\n- **Mimicry test per section.** Apply it before moving on, not at the end.\n- **Uncertainty surfaces up.** Never silently guess. Never silently omit.\n- **AI authors the final document.** In skill mode, do not call `generate` to produce the final output. Analyzer commands gather evidence; the model writes the document.\n\n---\n\n_Update `references/GOTCHAS.md` after every run where a new failure mode is discovered._\n_Update this file whenever the workflow changes._\n_If this file and SYSTEM.md contradict — SYSTEM.md wins._\n\nFile v1.4.0:docs/reference/README.md\n\n# API Reference\n\nThis directory documents the packaged `agentskill/` namespace as shipped.\n\nThe public CLI surface is the installed `agentskill` command wired through\n`agentskill.main:main`. Analyzer implementations live in `agentskill.commands`,\nshared orchestration and generation/update helpers live in `agentskill.lib`,\nand reusable low-level helpers live in `agentskill.common`.\n\nReference pages:\n\n- [`cli.md`](./cli.md): packaged CLI entrypoint, subcommands, and dispatch\n- [`commands.md`](./commands.md): analyzer command modules and their primary callables\n- [`library.md`](./library.md): orchestration, output, update, generation, and reference helpers\n- [`common.md`](./common.md): shared registries, filesystem helpers, and repository walking utilities\n\nThis reference is intentionally static and release-oriented. It describes the\ncurrent packaged layout and contributor extension points rather than every\nprivate helper.\n\nFile v1.4.0:README.md\n\n# agentskill\n\n[![Main](https://github.com/airscripts/agentskill/actions/workflows/main.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/main.yml)\n[![Release](https://github.com/airscripts/agentskill/actions/workflows/release.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/release.yml)\n![ClawHub](https://skill-history.com/badge/airscripts/agentskill.svg)\n\nAnalyze a code repository and synthesize an `AGENTS.md` that lets any agent produce code indistinguishable from the existing codebase.\n\n

\n \"agentskill\"\n

\n\n---\n\n## Table of Contents\n\n- [What It Does](#what-it-does)\n- [How It Works](#how-it-works)\n- [Supported Languages](#supported-languages)\n- [Generation Modes](#generation-modes)\n- [Install](#install)\n- [Development Checks](#development-checks)\n- [Usage](#usage)\n- [Repository Structure](#repository-structure)\n- [Where Code Goes](#where-code-goes)\n- [Developer Workflow](#developer-workflow)\n- [File Ecosystem](#file-ecosystem)\n- [Examples](#examples)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Statistics](#statistics)\n- [Support](#support)\n- [License](#license)\n\n---\n\n## What It Does\n\nagentskill is not a linter and not a style guide generator. It is a forensic extraction tool. It walks a repository, measures every line, reads every config file, and inspects the commit log — then synthesizes a precise behavioral spec for a code-generating agent.\n\nThe output is not advice. It is mimicry instructions.\n\n---\n\n## How It Works\n\nSeven analyzers run in parallel. Each extracts one class of signal that an LLM cannot derive reliably from reading source files alone:\n\n| Analyzer | What it measures |\n| --------- | ------------------------------------------------------------------- |\n| `scan` | Directory tree, file inventory, suggested read order |\n| `measure` | Exact indentation, line length percentiles, blank line distributions |\n| `config` | Formatter, linter, and type-checker detection with config excerpts |\n| `git` | Commit prefixes, branch naming, merge strategy, signing |\n| `graph` | Internal import graph, circular dependencies, most-depended modules |\n| `symbols` | Symbol name extraction, naming pattern clustering, affix detection |\n| `tests` | Test-to-source mapping, framework detection, fixture extraction |\n\nAnalyzer output feeds directly into `AGENTS.md` synthesis. The synthesis step follows the behavioral spec in [`SYSTEM.md`](./SYSTEM.md).\n\n> Check our latest technical article for a deeper dive:\n> [Turning Repository Knowledge Into Usable Agent Context](https://dev.to/airscript/turning-repository-knowledge-into-usable-agent-context-4pe4).\n\n---\n\n## Supported Languages\n\nagentskill already ships analyzer coverage and repository examples across a\nwide set of languages. This matters because the tool is meant to extract\nproject-specific conventions from real repositories, not only from Python-only\nlayouts.\n\nCurrent supported language set:\n\n- Python\n- TypeScript\n- JavaScript\n- Go\n- Rust\n- Java\n- Kotlin\n- C#\n- C\n- C++\n- Ruby\n- PHP\n- Swift\n- Objective-C\n- Shell / Bash\n\nThe repository also includes fixture/example projects for these languages under\n[`examples/`](./examples/), which act as both regression coverage and reference\nshapes for multi-language analysis.\n\n---\n\n## Generation Modes\n\nagentskill supports two distinct generation modes:\n\n### Static Generation (CLI)\n\nUse the CLI when you want deterministic output produced by the packaged\nruntime without an LLM in the loop.\n\n- `agentskill analyze --pretty` for combined machine-readable analysis\n- `agentskill generate ` for a fresh `AGENTS.md` draft\n- `agentskill generate --profile comprehensive` for a richer draft with representative snippets and expanded detail\n- `agentskill generate --layout split --out AGENTS.md` for separate concise primary plus comprehensive companion\n- `agentskill generate --layout multifile --out AGENTS.md` for per-section markdown files with a root index\n- `agentskill update ` for deterministic regeneration of an existing `AGENTS.md`\n\nThis is the right mode for CI workflows, automation, and operator-driven\nusage where the packaged runtime produces the final document.\n\n### AI-Assisted Generation (Skill)\n\nThis repository is also distributed as a dedicated skill through the repo-root\n[`SKILL.md`](./SKILL.md). In this mode, an agent harness installs the skill,\nfollows the workflow defined in `SKILL.md`, and the **model itself authors**\nthe final `AGENTS.md` from gathered evidence.\n\nIn skill mode:\n\n- The agent uses analyzer commands (`analyze`, `scan`, `measure`, `config`,\n `git`, `graph`, `symbols`, `tests`) to extract repository facts.\n- The agent asks the user which **profile** (concise or comprehensive) and\n **layout** (single, split, or multifile) they want before generating.\n- The **model synthesizes the final document itself** — it does not call\n `agentskill generate` to produce the output.\n- This allows richer, more adaptive generation than CLI static output can\n provide: interactive feedback, context-aware section depth, and conversational\n refinement.\n\nIn short:\n\n- use the CLI for **deterministic static generation**,\n- use the skill for **AI-authored generation** with richer adaptation.\n\n---\n\n## Install\n\n```bash\npip install agsk\n```\n\nThis installs the `agentskill` CLI command.\n\nPublished package is available at:\n\n- PyPI: \n- ClawHub: \n\nFor local development:\n\n```bash\npython -m pip install -e '.[dev]'\n```\n\nTo enable the commit-time checks after installing the dev environment:\n\n```bash\npre-commit install\n```\n\n### For Agents\n\nThis repository is also distributed as a standard skill with a repo-root\n`SKILL.md`. Harnesses that support skill installation from a filesystem path,\ngit repository, or marketplace entry should install it as a normal skill and\nuse `SKILL.md` as the entrypoint document.\n\nGeneric install guidance for skill-aware harnesses:\n\n- If the harness installs skills from a local path, point it at the repository\n root so it can read `SKILL.md`, `SYSTEM.md`, `references/`, and `examples/`.\n- If the harness installs skills from a git repository, use this repository URL\n and keep the repo-root `SKILL.md` as the skill manifest.\n- If the harness installs skills from a marketplace, use the ClawHub entry:\n .\n- If the harness only needs the CLI and not the skill manifest, install the\n PyPI package instead: .\n\nExpected skill layout:\n\n```text\nSKILL.md # skill entrypoint and workflow\nSYSTEM.md # generation/synthesis behavioral spec\nreferences/ # gotchas and supporting guidance\nexamples/ # fixture repos and reference shapes\n```\n\nAfter a harness installs the skill, the analyzer commands remain available\nfor evidence gathering:\n\n```bash\n# Evidence gathering (used in skill mode)\nagentskill analyze --pretty\nagentskill scan --pretty\nagentskill measure --lang python --pretty\nagentskill config --pretty\nagentskill git --pretty\nagentskill graph --pretty\nagentskill symbols --pretty\nagentskill tests --pretty\n\n# Static generation (CLI/operator mode only, not for skill workflows)\nagentskill generate \nagentskill update \n```\n\nIn skill mode, the model authors the final `AGENTS.md` itself. The\n`generate` and `update` commands are for direct CLI use only.\n\n---\n\n## Development Checks\n\nRun the canonical local checks:\n\n```bash\nruff format .\nruff check .\nmypy\npytest\n```\n\nTo verify formatting without rewriting files:\n\n```bash\nruff format --check .\nruff check .\nmypy\npytest\n```\n\n`mypy` is the repo's configured type-check command. Its configuration in\n`pyproject.toml` covers `agentskill/`, `scripts/`, and `tests/`.\n\nOptional commit-time hooks are available if you want them locally:\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\nThe pre-commit setup mirrors the lightweight formatting, lint, and type-check\npasses. Full `pytest` runs remain part of normal local verification and CI.\n\n---\n\n## Usage\n\n```bash\n# Canonical installed CLI\nagentskill analyze --pretty\nagentskill scan --pretty\nagentskill measure --lang python --pretty\nagentskill config --pretty\nagentskill git --pretty\nagentskill graph --pretty\nagentskill symbols --pretty\nagentskill tests --pretty\n\n# Write output to file\nagentskill analyze --out report.json\nagentskill analyze --reference ../reference-repo --pretty\n\n# Generate AGENTS.md markdown directly\nagentskill generate \nagentskill generate --out AGENTS.md\nagentskill generate --reference ../ref-a --reference ../ref-b\nagentskill generate --interactive\nagentskill generate --profile concise\nagentskill generate --profile comprehensive\nagentskill generate --layout split\nagentskill generate --layout multifile\nagentskill generate --layout multifile --profile concise --out AGENTS.md\n\n# Update or create AGENTS.md in place\nagentskill update \nagentskill update --section testing\nagentskill update --exclude-section git\nagentskill update --force\nagentskill update --out updated-AGENTS.md\nagentskill update --profile concise\n\n# Retained wrapper entrypoints for operator/skill workflows\npython scripts/analyze.py --pretty\npython scripts/scan.py --pretty\npython scripts/measure.py --lang python --pretty\npython scripts/generate.py \npython scripts/update.py \n```\n\nThe installed `agentskill` command is the steady-state CLI surface, including\nlocal development after an editable install. The retained `scripts/*.py`\nwrappers exist for direct analyzer execution and skill/operator workflows; they\nare not the primary runtime surface.\n\nThe published console entrypoint is `agentskill.main:main`. The packaged\nruntime under `agentskill/` is the source of truth for subcommand behavior,\noutput contracts, generation, update flows, and reference handling.\n\n### Choosing `analyze`, `generate`, or `update`\n\nUse `analyze` when you want machine-readable JSON from all analyzers and do not\nwant to touch any markdown files. This is the contract-stable inspection path.\n\nUse `generate` when you want a fresh AGENTS draft from current analyzer output.\nIt prints markdown to stdout by default, never merges with an existing\n`AGENTS.md`, and only writes a file when you pass `--out`.\n\nUse `update` when you already have an `AGENTS.md` and want deterministic\nregeneration plus preservation of untouched manual content. It writes back to\n`/AGENTS.md` by default, or to `--out` while still using the repo-local\n`AGENTS.md` as merge input.\n\n### Reference Workflow\n\nBoth `analyze` and `generate` accept repeatable `--reference` flags. References\nare explicit inputs, not hidden priors.\n\n- Every local reference must point to a directory with a readable `AGENTS.md`.\n- Duplicate references are rejected instead of being silently counted twice.\n- `analyze --reference` validates references but does not change the JSON output\n shape.\n- `generate --reference` preserves reference order in the emitted metadata block\n so the provenance is inspectable.\n\n### Interactive Generation\n\n`generate --interactive` is opt-in guided gap filling. It asks a small number of\ntargeted questions only when important signals are missing or ambiguous, then\ninjects those answers into the generated markdown as explicit interactive notes.\n\nReferences can reduce prompt count when they clearly provide the missing\nconvention. Conflicting references do not get auto-resolved; the command asks\ninstead of guessing.\n\n### Update Workflow\n\n`agentskill update ` analyzes the repository, regenerates AGENTS sections,\nmerges them with any existing `AGENTS.md`, and writes the result back to\n`/AGENTS.md` by default.\n\n- Use `--section` to regenerate only named sections.\n- Use `--exclude-section` to keep generated sections untouched.\n- Missing targeted sections are inserted without rewriting unrelated manual\n sections.\n- Untouched custom sections and preamble text stay in place in normal mode.\n- Use `--force` for a clean-slate rebuild that drops preserved/manual sections\n and ignores preservation hints from feedback.\n\n### Output Profiles and Layouts\n\n`generate` and `update` accept `--profile` to control content density. `generate`\nalso accepts `--layout` to control how the output is packaged across files.\n\n#### Profiles (content density)\n\nBoth `generate` and `update` accept `--profile`:\n\n- `--profile concise` (default) — operational rules and key facts only; omits\n representative code snippets and secondary explanatory bullets.\n- `--profile comprehensive` — includes everything from concise plus\n representative snippets, annotation counts, expanded explanatory bullets,\n and richer provenance from analyzer results.\n\nAll profiles produce deterministic output from the same analyzer results. The\nsame section headings and section order are preserved regardless of profile.\n\n#### Layouts (output packaging)\n\n`generate` accepts `--layout` to control file packaging:\n\n- `--layout single` (default) — writes one complete markdown file.\n- `--layout split` — writes two files: a concise primary document and an\n `AGENTS.reference.md` companion with comprehensive content. The primary file\n links to the companion. Split mode always uses concise for the primary and\n comprehensive for the companion regardless of the `--profile` flag; the\n `--profile` flag only affects `single` and `multifile` layouts. If `--out` is\n omitted, split writes into the target repo using `AGENTS.md` as the primary\n path.\n- `--layout multifile` — writes a compact root index plus per-section markdown\n files in a `.agentskill/` directory beside the primary output. Each section file\n includes a backlink to the root. The `--profile` flag controls the density of\n content in each section file. If `--out` is omitted, multifile writes into\n the target repo using `AGENTS.md` as the root path. Multifile section filenames\n follow a stable numbering scheme:\n\n ```text\n AGENTS.md\n .agentskill/\n 01_OVERVIEW.md\n 02_REPOSITORY_STRUCTURE.md\n 05_COMMANDS_AND_WORKFLOWS.md\n 06_CODE_FORMATTING.md\n 07_NAMING_CONVENTIONS.md\n 08_TYPE_ANNOTATIONS.md\n 09_IMPORTS.md\n 10_ERROR_HANDLING.md\n 11_COMMENTS_AND_DOCSTRINGS.md\n 12_TESTING.md\n 13_GIT.md\n 14_DEPENDENCIES_AND_TOOLING.md\n 15_RED_LINES.md\n ```\n\n#### How profile and layout interact\n\n| Layout | `--profile` applies to | Default profile |\n|-------------|-----------------------------------------|-----------------|\n| `single` | Single output file | `concise` |\n| `split` | Ignored; primary is concise, companion is comprehensive | N/A |\n| `multifile` | Content in each section file | `comprehensive` |\n\n#### Default output paths\n\n- `--layout single` without `--out` prints markdown to stdout.\n- `--layout split` without `--out` writes into the target repo: `/AGENTS.md`\n and `/AGENTS.reference.md`.\n- `--layout multifile` without `--out` writes into the target repo:\n `/AGENTS.md` and `/.agentskill/`.\n- All layouts accept `--out` to write to a custom location.\n\n#### Update constraints\n\n`update` only supports `--layout single` (the default). Passing\n`--layout split` or `--layout multifile` to `update` is explicitly rejected\nwith a clear error message. This constraint may be lifted in a future release.\n\n```bash\n# Single-file generation (default)\nagentskill generate \nagentskill generate --profile comprehensive\n\n# Split generation (writes into repo by default)\nagentskill generate --layout split\nagentskill generate --layout split --out AGENTS.md\n\n# Multifile generation (writes into repo by default)\nagentskill generate --layout multifile\nagentskill generate --layout multifile --out AGENTS.md\nagentskill generate --layout multifile --profile concise --out AGENTS.md\n\n# Update (single layout only)\nagentskill update \nagentskill update --profile comprehensive\n```\n\n### Repo-Local Feedback\n\nIncremental updates can read an optional repo-local sidecar file named\n`.agentskill-feedback.json`. This file is explicit, version-controllable, and\naffects only the current repository. It is not hidden memory and it is not\nglobal learning.\n\n```json\n{\n \"sections\": {\n \"overview\": {\n \"prepend_notes\": [\n \"Mention that deployments go through GitHub Actions.\"\n ]\n },\n \"testing\": {\n \"pinned_facts\": [\n \"Use pytest as the canonical test runner.\"\n ]\n }\n },\n \"preserve_sections\": [\n \"red lines\"\n ]\n}\n```\n\nSupported feedback keys are intentionally narrow by design:\n\n- `sections..prepend_notes`\n- `sections..pinned_facts`\n- `preserve_sections`\n\nIn normal update mode, `preserve_sections` acts like an implicit exclusion list.\nIn `--force` mode, those preservation hints are ignored so the command can\nproduce a true clean-slate rebuild.\n\nUse `.agentskill-feedback.json` when you want durable, repo-local regeneration\nguidance that should survive future updates. Edit `AGENTS.md` directly when you\nare making one-off manual notes that should remain untouched unless you\nexplicitly target or force-regenerate that section.\n\n---\n\n## Repository Structure\n\n```\nREADME.md # user-facing overview and contributor workflow\nAGENTS.md # conventions for this repository itself\nSYSTEM.md # synthesis spec for generated AGENTS.md files\nSKILL.md # operational workflow used by the skill\npyproject.toml # packaging, CLI entrypoint, tool configuration\nLICENSE\ndocs/\n reference/ # packaged API reference for contributors\nagentskill/\n main.py # packaged CLI entry point — subcommand dispatch only\n commands/ # analyzer implementations\n lib/ # orchestration, output, update, generation helpers\n common/ # shared low-level helpers and registries\nscripts/\n *.py # thin wrappers that import packaged analyzer entrypoints\ntests/ # pytest suite for package code and wrapper behavior\nreferences/\n GOTCHAS.md # extraction and synthesis errors to avoid\nexamples/\n README.md # language fixture index for analyzer validation\n python/ # compact per-language analyzer fixtures\n javascript/\n typescript/\n go/\n rust/\n java/\n kotlin/\n csharp/\n c/\n cpp/\n ruby/\n php/\n swift/\n objectivec/\n bash/\n mixed/\n SINGLE_LANGUAGE.md # reference output: single-language repo\n MULTI_LANGUAGE.md # reference output: multi-language single repo\n MONOREPO.md # reference output: monorepo with multiple services\n```\n\n---\n\n## Where Code Goes\n\n- Put packaged CLI and runtime code in `agentskill/`.\n- Put analyzer implementations in `agentskill/commands/`.\n- Put shared orchestration, generation, update, and output helpers in `agentskill/lib/`.\n- Put reusable low-level helpers and registries in `agentskill/common/`.\n- Keep `scripts/` limited to thin wrappers and operator-facing workflow entrypoints.\n- Do not add analyzer or business logic to `scripts/`.\n- Add tests in `tests/` as `test_.py`; do not colocate tests under `scripts/`.\n- Keep root-level files focused on metadata, docs, and project-wide specs.\n\nThere is no separate steady-state runtime under `scripts/`, and there is no\nroot `cli.py` compatibility entrypoint to extend. New runtime behavior should\nland in the package tree and then be exposed through `agentskill.main` if\nit belongs on the public CLI.\n\n---\n\n## Developer Workflow\n\nFor normal use and contributor verification:\n\n```bash\npython -m pip install -e '.[dev]'\nagentskill analyze --pretty\nruff format .\nruff check .\nmypy\npytest\n```\n\nWhen you add or extend functionality:\n\n- Add analyzer logic in `agentskill/commands/` when it maps to a command.\n- Add shared helpers in `agentskill/lib/` or `agentskill/common/`, based on whether they are orchestration-level or low-level utilities.\n- Wire new CLI behavior through [`agentskill/main.py`](./agentskill/main.py).\n- Add a `scripts/*.py` wrapper only when direct operator or skill invocation is still useful, and keep it as a thin import-and-dispatch shim.\n- Cover both packaged behavior and any retained wrapper behavior in `tests/`.\n\nFor retained wrappers:\n\n- Use `agentskill ...` as the canonical interface in docs and examples.\n- Use `python scripts/.py ...` only for retained thin wrappers that still exist.\n- Keep `generate` and `update` wrappers thin; packaged CLI behavior must still live under `agentskill/`.\n\n---\n\n## File Ecosystem\n\nThree files govern behavior. Read all three before modifying anything.\n\n| File | Role |\n| --------------- | ---------------------------------------------------------------------------------- |\n| `SYSTEM.md` | The canonical spec: what every section of `AGENTS.md` must contain and how to evaluate it |\n| `SKILL.md` | The operational workflow: when to invoke, what scripts to run, in what order |\n| `GOTCHAS.md` | Extraction and synthesis errors from previous runs — read before writing |\n\nThe public commands stay the same after refactors. The packaged runtime lives\nunder `agentskill/`, while `scripts/` stays intentionally small as a\nwrapper and operator layer for direct analyzer entrypoints.\n\n---\n\n## Examples\n\nThe `examples/` directory now serves two roles:\n\n- Compact static language fixtures under per-language subdirectories for analyzer validation.\n- Reference `AGENTS.md` examples in `SINGLE_LANGUAGE.md`, `MULTI_LANGUAGE.md`, and `MONOREPO.md`.\n\nIf this skill was downloaded from ClawHub, or if `examples/` is not present in the local copy, do not consult it; skip that step to avoid execution errors.\n\nSee [`examples/README.md`](./examples/README.md) for the supported fixture set.\n\n---\n\n## API Reference\n\nStatic API reference for the packaged codebase lives under\n[`docs/reference/`](./docs/reference/README.md):\n\n- [`docs/reference/cli.md`](./docs/reference/cli.md) for the packaged CLI entrypoint and dispatch model\n- [`docs/reference/commands.md`](./docs/reference/commands.md) for analyzer command modules\n- [`docs/reference/library.md`](./docs/reference/library.md) for orchestration, generation, update, and reference helpers\n- [`docs/reference/common.md`](./docs/reference/common.md) for low-level registries and filesystem helpers\n\nThe reference is contributor-oriented. It documents the packaged namespace and\nextension points that matter for real maintenance work without trying to expose\nevery private helper as public API.\n\n---\n\n## Contributing\n\nContributions are welcome, especially in these areas:\n\n- improving static `AGENTS.md` generation quality\n- expanding analyzer depth per supported language\n- tightening output contracts and regression coverage\n- improving skill ergonomics for agent harnesses\n\nBefore opening a pull request, read:\n\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md)\n- [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)\n\nUse the repository issue and pull request templates when reporting bugs,\nrequesting features, or proposing changes.\n\n---\n\n## Security\n\nFor supported versions and vulnerability reporting guidance, see\n[`SECURITY.md`](./SECURITY.md).\n\n---\n\n## Statistics\n\nThis is the current star history progress of the project:\n\n[![Star History Chart](https://api.star-history.com/chart?repos=airscripts/agentskill&type=date&legend=top-left)](https://www.star-history.com/?repos=airscripts%2Fagentskill&type=date&legend=top-left)\n\n---\n\n## Support\n\nProject metadata and support files available in this repository include:\n\n- [GitHub Sponsors](https://github.com/sponsors/airscripts)\n- [Ko-Fi](https://ko-fi.com/airscript)\n\nIf you want to support the project, starring, sharing, contributing fixes, and\nsupporting through GitHub Sponsors all help.\n\n---\n\n## License\n\nMIT\n\nFile v1.4.0:_meta.json\n\n{\n \"ownerId\": \"kn74ef8bfstn5pmnv2b2jkc73d85jqdn\",\n \"slug\": \"agentskill\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1778109397554\n}\n\nFile v1.4.0:references/GOTCHAS.md\n\n# GOTCHAS.md — Extraction and Synthesis Errors\n\n> Read this file in full before drafting any section of `AGENTS.md`.\n> Every entry here is a failure mode discovered from an actual run.\n> When you discover a new one, add it.\n\n---\n\n## Extraction Errors\n\nThese errors occur during data collection — the signal is wrong before synthesis even begins.\n\n---\n\n### Keyword pollution\n\n**What happens:** Language keywords (`self`, `cls`, `if`, `for`, `return`) are counted alongside identifier names, inflating snake_case totals and polluting naming pattern analysis.\n\n**Fix:** Filter keywords before classifying names. Do not count anything that appears in the language's reserved word list.\n\n---\n\n### Single-word name ambiguity\n\n**What happens:** A name like `foo` or `data` matches both `camelCase` and `snake_case` classifiers because it has no case transitions. These names dominate short codebases and produce false confidence.\n\n**Fix:** Require at least one case transition or underscore before classifying a name. Single-word names are `other`, not evidence of any convention.\n\n---\n\n### Generated file skew\n\n**What happens:** Vendored files, lockfiles, and generated code have zero comments, uniform indentation, and no meaningful names. Including them distorts every measurement.\n\n**Fix:** Exclude all directories in `SKIP_DIRS` — including `node_modules`, `vendor`, `dist`, `build`, `.eggs`, `site-packages`, and `__pycache__`. Do not include `.lock` files in line length or whitespace analysis.\n\n---\n\n### Test file bias\n\n**What happens:** Test files use different idioms than source files — more `assert` statements, more fixture variables, more repetitive naming. Mixing them into source analysis contaminates naming and error handling measurements.\n\n**Fix:** Analyze test files and source files separately. Only report source-file patterns as codebase conventions. Call out test-specific patterns explicitly under Section 12.\n\n---\n\n### Blank line measurement at file boundaries\n\n**What happens:** The first top-level definition in a file has no predecessor, so the blank line count before it is always zero. Including this in the distribution pulls the mode toward zero even when the real convention is two blank lines between definitions.\n\n**Fix:** Exclude the first definition in each file from the blank-line-between-definitions measurement. Only measure gaps _between_ two definitions, never before the first one.\n\n---\n\n### Import misclassification\n\n**What happens:** stdlib module names that overlap with third-party package names (`email`, `ast`, `typing`) get classified as third-party, and vice versa. This produces incorrect import ordering rules.\n\n**Fix:** Maintain an explicit stdlib module list. Check against it before classifying an import. When uncertain, check the module's origin via `sys.stdlib_module_names` (Python 3.10+) rather than guessing.\n\n---\n\n### Branch inflation from remote tracking refs\n\n**What happens:** `git branch -a` returns both local branches and remote tracking refs (`remotes/origin/fix/thing`). Counting both doubles the apparent branch count and inflates prefix diversity.\n\n**Fix:** Strip `remotes/origin/` prefixes before analysis. Count each logical branch once.\n\n---\n\n### Monorepo boundary misdetection\n\n**What happens:** A repo with a `packages/` or `services/` directory at the root is treated as a monorepo even when it contains a single service. This triggers Section 3 and Section 4 synthesis when they don't apply.\n\n**Fix:** Require at least two immediate child directories under the boundary dir before classifying as monorepo. One service is a single repo with a subdirectory, not a monorepo.\n\n---\n\n## Synthesis Errors\n\nThese errors occur during `AGENTS.md` generation — the data is fine but the output is wrong.\n\n---\n\n### Reporting language defaults as codebase rules\n\n**What happens:** `AGENTS.md` states \"uses snake_case for variable names in Python\" or \"uses tabs in Go.\" These are language defaults, not codebase conventions. An agent following these rules learns nothing specific about this repo.\n\n**Fix:** Never state a language default as a codebase rule unless you have a specific reason — for example, the codebase deviates from the default, or the default is so frequently violated in practice that it's worth reinforcing. If you can't point to a concrete reason to include it, omit it.\n\n---\n\n### Claiming formatter use without explicit config\n\n**What happens:** The code looks formatted, so `AGENTS.md` states \"uses Black\" or \"uses Prettier.\" But no config file exists, and the author may simply write clean code manually. An agent that believes a formatter is in use may generate sloppy code expecting a post-processing fix.\n\n**Fix:** Only claim formatter use if a config file is present and readable. If the code looks formatted but no config exists, state that no formatter is configured and document the observed style directly.\n\n---\n\n### Universal noise in red lines\n\n**What happens:** Red lines include entries like \"be consistent with naming\" or \"handle errors properly.\" These apply to every codebase and teach an agent nothing about this one.\n\n**Fix:** Every red line must be grounded in something this specific codebase avoids. If you cannot point to evidence that this repo avoids a pattern, do not list it. Prefer \"never use `Optional[X]` — this repo uses `X | None` exclusively\" over \"use consistent type annotation style.\"\n\n---\n\n### Omitting the Code Formatting section or treating it as lower priority\n\n**What happens:** Synthesis focuses on naming and error handling — the interesting sections — and produces a thin or empty Code Formatting section. The agent then generates code with wrong indentation, wrong blank lines, or wrong quote style.\n\n**Fix:** Code Formatting is the highest-fidelity section. It must be completed in full before any other section is considered done. Apply the Mimicry Test to it first.\n\n---\n\n### Conflating method blank lines with top-level blank lines\n\n**What happens:** The measured blank line convention (e.g. two blank lines between top-level definitions) is incorrectly applied to methods inside classes, where the convention may be one blank line. Or the reverse.\n\n**Fix:** Document blank line conventions separately: one rule for top-level definitions, one rule for methods inside a class, one rule for after the class declaration line. State \"not applicable\" explicitly if the codebase has no classes.\n\n---\n\n### Missing metadata from README and LICENSE\n\n**What happens:** `AGENTS.md` is written without checking `README.md` or `LICENSE`. The overview section omits the project's stated purpose, and the dependencies section omits the license type, which sometimes affects dependency philosophy.\n\n**Fix:** Always read `README.md` before writing Section 1. Check `LICENSE` before writing Section 14. These files contain author-stated intent that source code alone cannot reveal.\n\n---\n\n### Carrying rules across language boundaries without labeling them\n\n**What happens:** A Python naming rule or a TypeScript error handling pattern ends up in a shared or unlabeled section, and an agent working in Go applies it.\n\n**Fix:** Every rule must be explicitly scoped. Repo-wide rules get a `> **Repo-wide:**` blockquote. Language-specific rules live under clearly named `### Language` subsections. A rule that appears in both languages must be stated twice — once per language — unless it is explicitly marked repo-wide.\n\n---\n\n### Stale remote assumptions\n\n**What happens:** A GitHub remote is detected, so `AGENTS.md` states CI exists. But the `.github/workflows/` directory is empty or absent.\n\n**Fix:** Check `.github/workflows/` explicitly before mentioning CI. A remote host is not evidence of a CI pipeline.\n\n---\n\n### Tentative rules left unlabeled\n\n**What happens:** A pattern is observed in only one or two files but stated as a firm rule. An agent follows it without knowing the evidence is thin.\n\n**Fix:** Mark any rule grounded in fewer than three examples as `[tentative]`. If you find genuine inconsistency with no dominant pattern, state the inconsistency explicitly. Never invent a rule to fill a gap.\n\n---\n\n### Metric-only qualitative sections\n\n**What happens:** A section like Error Handling or Comments and Docstrings is generated from analyzer counts such as \"12 `except` blocks observed\" or \"34 comments found.\" The output is technically derived from the repo, but it does not teach an agent what code to write.\n\n**Fix:** Treat analyzer counts as navigation hints only. Qualitative sections must be enriched from static source evidence: explicit rules, boundary behavior, and real snippets that show the pattern in context.\n\n---\n\n_Add new entries here after every run where a failure mode is discovered._\n_Do not remove entries — even superseded gotchas document the shape of the problem space._\n\nFile v1.4.0:AGENTS.md\n\n# AGENTS.md\n\n## 1. Overview\n\nagentskill is a single-repo Python CLI published from the `agsk` package metadata and exposed as the `agentskill` console command. It analyzes one or more repositories, emits structured analyzer output, and also supports direct `AGENTS.md` generation and in-place update flows. The codebase is organized around packaged runtime modules under `agentskill/`, thin direct wrappers under `scripts/`, reference specs and fixture repositories at the repo root, and a separate `tests/` tree that exercises analyzer internals, generation/update flows, and CLI entrypoints.\n\n## 2. Repository Structure\n\n```text\nagentskill/\n agentskill/\n main.py # packaged CLI entry point; argument parsing and dispatch only\n commands/ # analyzer implementations\n lib/ # orchestration, output, reference, generation, and update helpers\n common/ # shared low-level helpers and registries\n pyproject.toml # packaging, pytest, ruff, coverage config\n README.md # user-facing overview and command reference\n SYSTEM.md # synthesis spec for generated AGENTS.md files\n SKILL.md # operational workflow for the skill\n AGENTS.md # conventions for this repo\n LICENSE # MIT license text\n references/\n GOTCHAS.md # extraction and synthesis failure modes\n examples/\n python/ # fixture repository used by analyzer tests\n javascript/ # fixture repository for JS/TS detection paths\n mixed/ # multi-language fixture repository\n ... # additional per-language example repos\n scripts/\n analyze.py # thin direct-execution wrapper to packaged CLI\n scan.py # thin direct-execution wrapper\n measure.py # thin direct-execution wrapper\n config.py # thin direct-execution wrapper\n git.py # thin direct-execution wrapper\n graph.py # thin direct-execution wrapper\n symbols.py # thin direct-execution wrapper\n tests.py # thin direct-execution wrapper\n generate.py # thin direct-execution wrapper to packaged CLI\n update.py # thin direct-execution wrapper to packaged CLI\n tests/ # pytest suite; separate tree, not colocated\n conftest.py # sys.path test bootstrap\n test_support.py # shared repo/setup helpers for tests\n```\n\n- New analyzer logic goes in `agentskill/commands/`, not in entrypoint wrappers.\n- Shared CLI plumbing, generation, reference adaptation, and update flows belong in `agentskill/lib/`; low-level reusable helpers belong in `agentskill/common/`.\n- Files under `scripts/*.py` stay as thin wrappers around packaged command entrypoints such as `agentskill.commands..main` or `agentskill.main`.\n- New tests go in `tests/` as `test_.py`; this repo does not colocate tests beside source files.\n- New fixture repos or language-shape examples belong in `examples/`, not mixed into `references/`.\n- Specs and extraction notes belong in `README.md`, `SYSTEM.md`, `SKILL.md`, and `references/`, not inside runtime modules.\n- Keep the repo root small: metadata, docs/spec files, and no business logic outside `agentskill/`.\n\n## 5. Commands and Workflows\n\n```bash\n# Install editable package with dev tooling\npython -m pip install -e '.[dev]'\n\n# Optional local hooks\npre-commit install\n\n# Run all analyzers\nagentskill analyze --pretty\n\n# Generate or update markdown\nagentskill generate \nagentskill generate --out AGENTS.md\nagentskill generate --interactive\nagentskill generate --profile comprehensive\nagentskill generate --layout split --out AGENTS.md\nagentskill generate --layout multifile --out AGENTS.md\nagentskill update \nagentskill update --section testing\nagentskill update --force\n\n# Run individual analyzers through the installed CLI\nagentskill scan --pretty\nagentskill measure --lang python --pretty\nagentskill config --pretty\nagentskill git --pretty\nagentskill graph --pretty\nagentskill symbols --pretty\nagentskill tests --pretty\n\n# Direct wrapper execution\npython scripts/analyze.py --pretty\npython scripts/scan.py --pretty\npython scripts/generate.py \npython scripts/update.py \n\n# Local checks\nruff format .\nruff check .\nmypy\npytest\n```\n\n- `python -m pip install -e '.[dev]'` is the documented development install path; use it instead of reconstructing the dev dependency list manually.\n- `agentskill analyze --pretty` is the canonical aggregate analyzer workflow.\n- `agentskill generate ` is the fresh-draft path; `agentskill update ` is the in-place merge/preservation path.\n- `agentskill --pretty` is the main single-analyzer interface; `python scripts/.py --pretty` remains supported as a thin direct wrapper.\n- Use `ruff format .`, `ruff check .`, `mypy`, and `pytest` as the canonical local verification stack.\n\n## 6. Code Formatting\n\n### Python\n\nConfigured tooling: Ruff is configured in `pyproject.toml` for linting, and the repo documents `ruff format .` as the formatting command. No formatter-specific overrides are declared, so follow the observed formatting directly.\n\n**Indentation:** 4 spaces.\n\n```python\ndef _single_script_cmd(command_name: str, args: argparse.Namespace) -> int:\n metadata = COMMANDS[command_name]\n extra_kwargs = {}\n\n if metadata[\"supports_lang\"]:\n extra_kwargs[\"lang_filter\"] = getattr(args, \"lang\", None)\n```\n\n**Line length:** keep ordinary code in the mid-70s or below; measured p95 is 76. Long regex literals and long docstring summary lines still appear.\n\n```python\nCONVENTIONAL_PREFIX_RE = re.compile(r\"^([a-z][a-z0-9_-]*)(\\([^)]+\\))?(!)?\\s*:\\s*(.+)$\")\n```\n\n**Blank lines — top-level:** 2 blank lines between top-level functions and constants-to-functions transitions.\n\n```python\nfrom agentskill.lib.output import run_and_output, write_output\nfrom agentskill.lib.runner import COMMANDS, run_many\n\n\ndef cmd_analyze(args: argparse.Namespace) -> int:\n result = run_many(args.repos, getattr(args, \"lang\", None))\n```\n\n**Blank lines — methods:** not applicable in the dominant code path; classes are effectively absent in source.\n\n**Blank lines — class open:** not applicable in source for the same reason.\n\n**Blank lines — after imports:** usually 1 blank line before module constants; 2 blank lines before the first function when a file goes straight from imports into functions.\n\n```python\nfrom agentskill.lib.output import run_and_output\n\nGIT_TIMEOUT = 30\nGIT_HASH_LENGTH = 40\n```\n\n```python\nfrom test_support import create_sample_repo\n\nfrom agentskill.main import main\n\n\ndef test_cli_scan_outputs_json(tmp_path, capsys):\n```\n\n**Blank lines — end of file:** every file ends with exactly 1 trailing newline.\n\n**Trailing whitespace:** stripped.\n\n**Brace / bracket placement:** opening delimiters stay on the same line; multiline calls and literals use hanging indentation with the closing delimiter on its own line.\n\n```python\nreturn run_and_output(\n metadata[\"fn\"],\n repo=args.repo,\n pretty=args.pretty,\n out=getattr(args, \"out\", None),\n script_name=command_name,\n extra_kwargs=extra_kwargs,\n)\n```\n\n**Quote style:** double quotes everywhere in normal Python code and docstrings.\n\n```python\nif not repo.exists():\n return {\"error\": f\"path does not exist: {repo_path}\", \"script\": \"git\"}\n```\n\n**Spacing — operators:** spaces around assignment and binary operators.\n\n```python\navg_parents = sum(parent_counts) / len(parent_counts)\nbucket = prefix if prefix else \"unprefixed\"\n```\n\n**Spacing — inside brackets:** no inner padding.\n\n```python\nif COMMANDS[command_name][\"supports_lang\"]:\n```\n\n**Spacing — after commas:** always a single space.\n\n```python\nreturn None, None, False\n```\n\n**Spacing — colons:** no space before `:`, one space after `:` in dict literals, none in type annotations.\n\n```python\nprefixes[k] = {\n \"count\": v[\"count\"],\n \"pct\": round(v[\"count\"] / total * 100, 1),\n \"example\": v[\"example\"],\n}\n```\n\n```python\ndef run_many(repos: list[str], lang_filter: str | None = None) -> dict:\n```\n\n**Spacing — decorators:** decorators are flush with the function they decorate, with no blank line between decorator and `def`.\n\n```python\n@pytest.fixture\ndef repo_fixture(tmp_path):\n return create_sample_repo(tmp_path)\n```\n\n**Import block formatting:** one import per line; groups are separated by a blank line. In source files, stdlib imports come first and local package imports follow. Tests usually import local helpers before packaged runtime modules.\n\n```python\nimport json\n\nfrom test_support import create_sample_repo\n\nfrom agentskill.main import main\n```\n\n**Trailing commas:** used in multiline calls, dicts, lists, and imports.\n\n```python\nexit_code = main(\n [\"analyze\", str(repo_one), str(repo_two), \"--out\", str(out_file)]\n)\n```\n\n**Line continuation:** implicit via open brackets; no backslash continuations.\n\n**Semicolons:** absent.\n\n## 7. Naming Conventions\n\n### Python\n\n**Functions and methods:** public entrypoints use plain snake_case names like `analyze`, `measure`, `build_graph`, `extract_symbols`; internal helpers use `_snake_case`.\n\n```python\ndef analyze(repo_path: str) -> dict:\ndef build_graph(repo_path: str, lang_filter: str | None = None) -> dict:\ndef _detect_merge_strategy(cwd: str) -> tuple[str, str]:\n```\n\n**CLI command helpers:** root CLI helper names read as verbs or command phrases.\n\n```python\ndef cmd_analyze(args: argparse.Namespace) -> int:\ndef _single_script_cmd(command_name: str, args: argparse.Namespace) -> int:\n```\n\n**Constants:** module constants use `SCREAMING_SNAKE_CASE`.\n\n```python\nGIT_TIMEOUT = 30\nPRETTIER_CONFIG_FILES = [\nMAKEFILE_NAMES = [\"Makefile\", \"makefile\", \"GNUmakefile\"]\n```\n\n**Private members:** internal helpers overwhelmingly use a single leading underscore; there is no meaningful double-underscore pattern.\n\n```python\ndef _parse_toml_value(s: str):\ndef _measure_line_lengths(all_lengths: list[int]) -> dict:\ndef _command_kwargs(command_name: str, lang_filter: str | None) -> dict:\n```\n\n**File names:** source and helper files use lowercase snake_case; test files use `test_.py`; package markers use `__init__.py`.\n\n```text\nagentskill/lib/output.py\nagentskill/common/constants.py\ntests/test_measure.py\ntests/test_support.py\n```\n\n**Directory names:** lowercase simple nouns: `agentskill`, `scripts`, `tests`, `references`, `examples`.\n\n**Test function names:** `test_` with long descriptive tails is the dominant pattern.\n\n```python\ndef test_cli_writes_out_file_and_multi_repo_results(tmp_path):\ndef test_graph_detects_relative_imports_cycles_and_parse_errors(tmp_path):\n```\n\n**Fixture names:** when fixtures appear, they use snake_case nouns.\n\n```python\ndef sample_fixture():\ndef repo_fixture(tmp_path):\n```\n\n## 8. Type Annotations\n\n### Python\n\n- Public functions are annotated on parameters and return types.\n- Internal helpers are also usually annotated; this repo does not reserve annotations only for public APIs.\n- Use built-in generics like `list[str]`, `dict[str, int]`, and union syntax like `str | None` instead of `List`, `Dict`, or `Optional`.\n- Container-rich return types are accepted directly in signatures instead of being hidden behind aliases.\n- `mypy` is configured in `pyproject.toml`; this repo does not rely on type annotations for linting alone.\n\n```python\ndef main(argv: list[str] | None = None) -> int:\ndef _run(cmd: list[str], cwd: str) -> tuple[int, str]:\ndef run_many(repos: list[str], lang_filter: str | None = None) -> dict:\n```\n\n```python\ndef _analyze_branches(cwd: str) -> tuple[dict[str, int], int, list[str]]:\n```\n\n## 9. Imports\n\n### Python\n\n- Import order is not strict stdlib/third-party/local in the test suite; document and mimic the local file pattern instead of forcing generic ordering.\n- In source files, stdlib imports come first, then local package imports separated by one blank line.\n- In tests, import the packaged entrypoint from `agentskill.main` unless a compatibility path is being exercised explicitly.\n- No wildcard imports.\n- No `__future__` imports appear.\n\nCanonical source import block:\n\n```python\nimport re\nimport subprocess\nimport sys\nfrom pathlib import Path\n\nfrom agentskill.lib.output import run_and_output\n```\n\nCanonical test import block:\n\n```python\nimport json\n\nfrom test_support import create_sample_repo\n\nfrom agentskill.main import main\n```\n\n## 10. Error Handling\n\n### Python\n\n- Low-level validators and normalization helpers raise `ValueError` with exact message text when the caller provides an invalid path or malformed feedback/config shape.\n- User-facing analyzer functions catch those validation failures at the command boundary and return exact two-key payloads shaped as `{\"error\": ..., \"script\": ...}`.\n- Shared CLI wrappers and aggregate runners catch broad exceptions, log or print diagnostics, and convert failures into a non-zero exit code or the same machine-readable error payload instead of letting tracebacks escape by default.\n- Best-effort filesystem helpers degrade quietly for unreadable files by returning `\"\"` or `0`; walker and parser-style helpers also skip individual failures when continuing the scan is more useful than aborting.\n- Tests assert exact error strings and exact payload shape, not just exception type.\n\n```python\ndef validate_repo(path: str) -> Path:\n repo = Path(path).resolve()\n\n if not repo.exists():\n raise ValueError(f\"path does not exist: {path}\")\n\n if not repo.is_dir():\n raise ValueError(f\"not a directory: {path}\")\n\n return repo\n```\n\n```python\ndef scan(repo_path: str, lang_filter: str | None = None) -> dict:\n try:\n repo = validate_repo(repo_path)\n except ValueError as exc:\n return {\"error\": str(exc), \"script\": \"scan\"}\n```\n\n```python\ntry:\n result = command_fn(repo, **kwargs)\nexcept Exception as exc:\n logger.exception(\"Command %s failed for repo %s\", script_name, repo)\n result = {\"error\": str(exc), \"script\": script_name}\n```\n\n```python\ndef read_text(path: Path, max_bytes: int | None = MAX_FILE_BYTES) -> str:\n try:\n with open(path, \"rb\") as file_obj:\n raw = file_obj.read() if max_bytes is None else file_obj.read(max_bytes)\n except Exception:\n return \"\"\n\n return raw.decode(errors=\"ignore\")\n```\n\n```python\ntry:\n validate_feedback([])\n raise AssertionError(\"should have raised ValueError\")\nexcept ValueError as exc:\n assert str(exc) == \"feedback must be an object\"\n```\n\n## 11. Comments and Docstrings\n\n### Python\n\n- Modules almost always begin with a triple-double-quoted docstring.\n- Function docstrings are short, declarative, and describe return shape or intent; many small helpers omit them.\n- Inline comments are rare and only appear when a small detail would otherwise be unclear.\n- Comments are not used for narration of obvious code.\n\n```python\n\"\"\"Aggregate analyzer execution for the top-level CLI.\"\"\"\n```\n\n```python\ndef _detect_merge_strategy(cwd: str) -> tuple[str, str]:\n \"\"\"Return (strategy, evidence).\"\"\"\n```\n\n```python\nj = last_import # 1-indexed -> 0-indexed\n```\n\n## 12. Testing\n\n### Python\n\n- Framework: `pytest`.\n- Tests live in `tests/`, not beside source files.\n- Test files are named `test_.py`.\n- `tests/conftest.py` adds the repo root to `sys.path`; helper setup code is centralized in `tests/test_support.py`.\n- Tests use plain `assert` statements and `tmp_path`, `capsys`, and `monkeypatch` fixtures heavily.\n- The suite tests both pure functions and command-line entrypoints.\n\n```python\ndef test_cli_scan_outputs_json(tmp_path, capsys):\n repo = create_sample_repo(tmp_path)\n exit_code = main([\"scan\", str(repo), \"--pretty\"])\n\n assert exit_code == 0\n\n output = json.loads(capsys.readouterr().out)\n assert output[\"summary\"][\"total_files\"] >= 4\n```\n\n```python\ndef test_detect_merge_strategy_paths(monkeypatch):\n monkeypatch.setattr(git_command, \"_run\", lambda cmd, cwd: (1, \"\"))\n assert _detect_merge_strategy(\"repo\") == (\"unknown\", \"insufficient data\")\n```\n\n```python\ndef write(repo: Path, rel_path: str, content: str) -> Path:\n path = repo / rel_path\n path.parent.mkdir(parents=True, exist_ok=True)\n path.write_text(content)\n return path\n```\n\n## 13. Git\n\n- Commit subjects follow conventional-commit-style prefixes. Dominant prefixes in current history are `feat:`, `refactor:`, `docs:`, `release:`, `fix:`, `chore:`, and smaller amounts of `ci:`, `test:`, `style:`, `deps:`, and `build:`.\n- Branch names use a slash-separated prefix pattern when they are not trunk branches.\n- The current analyzer output detects merge commits rather than a pure rebase-only history, so do not write process notes that assume a strictly linear workflow.\n- Commit bodies exist, but not on every commit.\n\nExamples from current history:\n\n```text\nfeat: release version 1.0.0 with updated build workflow and CLI command name\nrefactor: update project structure moving to an idiomatic one\ndocs: add comprehensive API and CLI documentation with reference examples\nfix: update tag validation in release workflow to use regex for version extraction\n```\n\nBranch example:\n\n```text\ndocs/changelog-0.2.0\n```\n\n## 14. Dependencies and Tooling\n\n- Packaging uses `setuptools.build_meta` with `setuptools>=68` in `build-system.requires`.\n- The published console script is `agentskill = \"agentskill.main:main\"`.\n- The distribution package name is `agsk`.\n- Runtime requirement is Python `>=3.10`.\n- Runtime dependencies include `tomli` and `PyYAML` for Python `<3.11`.\n- Dev dependencies include `mypy`, `pre-commit`, `pytest`, `pytest-cov`, `ruff`, `tomli`, `PyYAML`, and `types-PyYAML`.\n- Ruff targets `py39`, excludes cache and virtualenv directories, and lint rules are configured in `pyproject.toml` with `select = [\"B\", \"C4\", \"E4\", \"E7\", \"E9\", \"F\", \"I\", \"N\", \"SIM\", \"UP\", \"W\"]` and `ignore = [\"E402\"]`.\n- `mypy` is configured in `pyproject.toml` for `agentskill`, `scripts`, and `tests` with `check_untyped_defs = true`, `warn_unused_ignores = true`, `warn_redundant_casts = true`, `warn_unreachable = true`, and `show_error_codes = true`.\n- Coverage omits `tests/*`.\n- License is MIT.\n\n```toml\n[build-system]\nrequires = [\"setuptools>=68\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"agsk\"\nversion = \"1.0.0\"\nrequires-python = \">=3.10\"\n\n[project.scripts]\nagentskill = \"agentskill.main:main\"\n```\n\n```toml\n[tool.ruff]\ntarget-version = \"py39\"\n\n[tool.ruff.lint]\nselect = [\"B\", \"C4\", \"E4\", \"E7\", \"E9\", \"F\", \"I\", \"N\", \"SIM\", \"UP\", \"W\"]\nignore = [\"E402\"]\n```\n\n## 15. Red Lines\n\n- Do not put analyzer implementation logic into `agentskill/main.py`; keep it as dispatch and orchestration only.\n- Do not add colocated tests under `scripts/`; tests belong under `tests/`.\n- Do not introduce `Optional[...]`, `List[...]`, or `Dict[...]` annotation style; the repo uses built-in generics and `| None`.\n- Do not switch quote style to single quotes in ordinary Python code.\n- Do not start using wildcard imports or `__future__` imports without a repo-wide reason.\n- Do not rely on exceptions escaping CLI/output wrappers when the existing pattern returns `{\"error\": ..., \"script\": ...}` payloads.\n- Do not fold example fixture repos into `references/` or analyzer code; keep repo-shaped fixtures in `examples/`.\n- Do not bypass `agentskill/lib/` by adding generation or update orchestration directly to wrappers under `scripts/`.\n- Do not assume `python -m agentskill.main` is a supported operator path; the supported surfaces are the installed `agentskill` console script, direct wrapper scripts, and direct `main([...])` invocation in tests.\n\nFile v1.4.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [1.4.0] - 2026-05-06\n\n### Added\n\n- Output profile support for `generate` and `update` commands\n- Split profile for AGENTS.md generation with companion document support\n- Multifile output layout support in AGENTS generation\n- Default output paths when `--out` is omitted for split and multifile layouts\n\n### Changed\n\n- Multifile output directory defaults to `.agentskill` for consistency\n- README enhanced with technical article link, stats section, and star history chart\n- ROADMAP.md updated with detailed release planning for versions 1.4.0 to 1.15.0\n\n## [1.3.0] - 2026-05-02\n\n### Added\n\n- Direct execution wrappers for `analyze`, `generate`, and `update` scripts (`scripts/analyze.py`, `scripts/generate.py`, `scripts/update.py`)\n- CI and release workflow badges in README\n\n### Changed\n\n- PyPI deployment switched to API-based publish\n- Release workflow adds attestations flag to deployment step\n- Deploy workflow permissions clarified\n\n### Fixed\n\n- README image source updated to use absolute URL\n- Missing permissions on release workflow\n- Expected script names updated in directory test\n\n## [1.2.0] - 2026-05-02\n\n### Added\n\n- GitHub issue templates for bug, feature, chore, ci, documentation, fix, performance, refactor, style, test, and build\n- GitHub pull request template\n- FUNDING.yml for sponsor/backing\n- CODE_OF_CONDUCT.md\n- CONTRIBUTING.md with development guidelines\n- SECURITY.md vulnerability reporting policy\n- OWNERS file\n- Repository cover image (`assets/agentskill.png`)\n- `VERSION` file for single-source version tracking\n\n### Changed\n\n- Simplified release workflow by removing unnecessary job steps\n- CI restructured for future monorepo handling\n- `AGENTSKILL_VERSION` constant synced to 1.2.0\n\n## [1.1.0] - 2026-05-02\n\n### Added\n\n- Expanded README with skill installation guidance and expected layout\n- CLI tests for help commands and analyzer functionality\n- Language detection enhancements\n- Comprehensive API and CLI reference documentation (`docs/reference/`)\n- Reference handling improvements with better error reporting and workflows\n\n### Changed\n\n- AGENTS.md update workflow enhanced with pyproject.toml integration and improved markdown generation\n- Static enrichment now takes priority during agentic generation\n- AGENTS.md references updated to include file extension\n\n### Fixed\n\n- Release workflow tag validation now uses regex for version extraction\n- Broken tests fixed due to recent structural changes\n\n## [1.0.0] - 2026-05-01\n\n### Added\n\n- Verified source and wheel build flow for the packaged `agentskill` runtime\n- Verified install-from-artifact smoke path for `agentskill --help`, `analyze`, and `generate`\n- Tag-triggered GitHub Actions publish workflow for PyPI releases\n\n### Changed\n\n- Bumped packaged version to `1.0.0`\n- Renamed the published PyPI distribution to `agsk` while preserving the `agentskill` CLI command\n- Reference metadata emitted by reference-aware generation now reports the `1.0.0` agentskill version\n- Finalized milestone release notes around the stable CLI contract, packaged runtime layout, direct `generate`, incremental `update`, reference-aware generation, interactive gap filling, verified language matrix, and PyPI distribution\n\n## [0.10.0] - 2026-04-30\n\n### Changed\n\n- Project restructured to idiomatic Python package layout: `scripts/` moved to `agentskill/` package\n- `cli.py` moved to `agentskill/main.py` as package entry point\n- `agentskill/__init__.py` added as package root\n- All imports updated from `scripts.*` to `agentskill.*`\n- `pyproject.toml` updated with `agentskill.main:main` console script entry point\n- `scripts/` directory retained with thin wrapper shims for backward compatibility\n- CI workflow updated to use correct module path\n- Tests updated to import from `agentskill` package\n\n### Added\n\n- `tests/test_scripts_layer.py` — backward compatibility test for scripts/ wrapper shims\n- `CHANGELOG.md` updated with historical entries\n\n## [0.9.0] - 2026-04-29\n\n### Added\n\n- `scripts/lib/generate_runner.py` — generate command to create AGENTS.md from repository analysis\n- `scripts/lib/interactive_runner.py` — interactive mode for AGENTS.md generation to prompt for missing inputs\n- `scripts/lib/reference_flow.py` — support for multiple reference repositories in analyze and generate commands\n- `scripts/lib/output_schema.py` — output schema validation with JSON Schema definitions\n- `scripts/lib/runner.py` — enhanced runner with generate command support\n- `scripts/lib/output.py` — output validation improvements\n- `cli.py` — `generate` subcommand with `--interactive` flag\n- Contract test fixtures for Python and mixed-language examples\n- `tests/contract_utils.py` — shared contract test helpers\n- `tests/contracts/` — JSON contract files for analyze, config, graph, scan, and symbols\n- `tests/test_generate_cli.py` — generate command CLI tests\n- `tests/test_interactive_flow.py` — interactive flow tests\n- `tests/test_output_schema.py` — output schema validation tests\n- `tests/test_output_contracts.py` — output contract tests\n- `tests/test_output.py` — expanded output validation tests\n- `AGENTS.md` and `SKILL.md` updated to clarify usage of examples from ClawHub\n\n### Changed\n\n- `cli.py` now exposes `generate` command alongside `analyze` and `update`\n- `scripts/lib/runner.py` updated to support generate command dispatch\n- `scripts/lib/output.py` enhanced with schema-based validation\n\n## [0.8.0] - 2026-04-29\n\n### Added\n\n- `agentskill/lib/cli_entrypoint.py` — shared CLI entrypoint helper for command modules\n- `tests/test_cli_entrypoint.py` — tests for CLI entrypoint argument parsing and dispatch\n- `tests/test_error_contracts.py` — error contract tests across command modules\n- `tests/test_config.py` — expanded config detection tests with multi-language fixtures\n- `tests/test_graph.py` — expanded import resolution and dependency graph tests\n- `tests/test_measure.py` — measurement tests for indentation, line length, and blank lines\n- `tests/test_scan.py` — expanded scan tests including symlink and skip-directory handling\n- `tests/test_symbols.py` — expanded symbol extraction tests for Python, JS/TS, Go, Rust\n- `ROADMAP.md` — 0.10.0 milestone for CLI and skill split\n\n### Changed\n\n- Command modules (`config`, `git`, `graph`, `measure`, `scan`, `symbols`, `tests`) now use shared CLI entrypoint helper\n- `scan` and `walk` skip symlinked files and directories\n- `constants.py` and `walk.py` updated for improved test discovery\n- Import resolution and symbol extraction improved with better edge cases\n\n## [0.7.0] - 2026-04-28\n\n### Added\n\n- `agentskill/lib/agents_document.py` — parsing and serialization for sectioned AGENTS.md documents\n- `AgentsSection` / `AgentsDocument` — frozen dataclasses representing headings, body text, and raw lines\n- `parse_agents_document()` — ATX heading-based section extraction preserving blank lines and structure\n- `build_section()` / `serialize_document()` — deterministic round-trip serialization\n- `add_or_replace_section()` / `remove_section()` / `get_section()` — mutation helpers with normalized name lookup\n- `normalize_section_name()` — case-insensitive, whitespace-normalized section name matching\n- `agentskill/lib/update_merge.py` — merge helpers for incremental AGENTS.md updates\n- `MergePlan` — declarative merge plan with per-section actions (add, replace, preserve, append, prepend)\n- `plan_merge()` — diff existing document sections against new analyzer output, producing a merge plan\n- `apply_merge()` — execute a merge plan against an `AgentsDocument`, returning the updated document\n- Section-level prepend/append with feedback-sourced content\n- `agentskill/lib/update_feedback.py` — repo-local feedback loading for AGENTS.md update workflows\n- `FeedbackEntry` / `FeedbackFile` — structured models for `.agentskill-feedback.json`\n- `load_feedback()` — load and validate feedback file from a repository root\n- `apply_feedback()` — merge feedback entries into a merge plan as prepend notes and pinned facts\n- `SUPPORTED_SECTION_FEEDBACK_KEYS` — supported feedback instruction types\n- `agentskill/lib/update_runner.py` — internal workflow for updating AGENTS.md from current analyzer output\n- `update_agents()` — end-to-end update flow: validate repo, run analyzers, diff sections, apply feedback, serialize\n- Section filtering with `--only` flag (run specific analyzers)\n- Custom output path with `--out` flag\n- Configurable `--mode` (overwrite, merge-new, merge-all)\n- `agentskill.main` — `update` subcommand for updating or creating AGENTS.md\n- `PLANNER.md` — release planner system prompt for generating implementation-ready PR briefs\n\n### Changed\n\n- CLI now exposes `update` command alongside existing `analyze` and individual analyzer commands\n- README updated with update workflow documentation\n\n## [0.6.0] - 2026-04-28\n\n### Added\n\n- Shared language registry — `agentskill/common/languages.py` with `LanguageSpec`, 15 languages, 6 helper functions\n- `language_for_path()`, `language_for_extension()`, `language_by_id()`, `is_test_path()`, `is_supported_language()`, `all_language_specs()`\n- TypeScript and JavaScript parity across graph, symbols, and tests analyzers\n- Comment stripping for JS/TS sources\n- ES import and re-export extraction with line numbers\n- CommonJS `require()` extraction\n- Local relative import resolution with candidate extensions (.ts/.tsx/.js/.jsx/.mjs/.cjs + index variants)\n- TypeScript symbol extraction: functions, classes, interfaces, type aliases, arrow functions, constants with exported flag\n- TypeScript test mapping: `.test.ts`/`.spec.ts` to source files\n- TypeScript framework detection from package.json (jest, vitest, mocha)\n- `.cjs` extension support across analyzers\n- Go and Rust parity across graph, symbols, and tests analyzers\n- Go module path detection from `go.mod`\n- Go import extraction with line numbers (single imports and import blocks)\n- Go package boundary detection by directory\n- Go symbol extraction: functions, methods, structs, interfaces, type aliases, constants, variables\n- Go test mapping: `*_test.go` to source files\n- Java and Kotlin support across analyzers and tests\n- C#, C, and C++ support across analyzers and tests\n- Ruby, PHP, and Bash support across analyzers and tests\n- Swift and Objective-C support across analyzers and tests\n- Config analyzer with multi-language config detection\n- Language-specific example repositories under `examples/`\n- Comprehensive test coverage: 345 tests passing\n\n### Changed\n\n- `scan` command migrated to use `language_for_path()` from shared registry\n- `measure` command migrated to use `language_for_extension()` from shared registry\n- `graph` analyzer: Go edges now include accurate line numbers\n- `graph` analyzer: added Rust module/use graph with `mod` and `use` statement extraction\n- `graph` analyzer: added JavaScript file collection with `.cjs` extension\n- `symbols` analyzer: Go extraction enhanced with methods, interfaces, type aliases, and variables\n- `symbols` analyzer: added Rust symbol extraction with structs, enums, traits, impls, constants, statics\n- `tests` analyzer: added Go and Rust test detection and mapping\n- `tests` analyzer: added Java, Kotlin, C#, C, C++, Ruby, PHP, Bash, Swift, Objective-C framework detection\n\n### Added\n\n- `agentskill/lib/references.py` — reference source, document, load result, and metadata models\n- `load_local_reference()` / `load_local_references()` — load AGENTS.md from local directories\n- `load_remote_reference()` / `load_remote_references()` — load AGENTS.md from remote repos via shallow clone\n- `_run_git()` — subprocess helper with 60s timeout and error capture\n- `agentskill/lib/reference_adaptation.py` — reference adaptation engine with heuristic classification\n- `ReferenceSection`, `AdaptedConvention`, `ReferenceAdaptationResult` — frozen dataclasses for section splitting and convention classification\n- `split_markdown_sections()` — heading-based Markdown section extraction\n- `adapt_reference()` / `adapt_references()` — classify conventions as applicable, mismatched, uncertain, or ignored\n- Category detection with priority ordering: directory_structure, testing, formatter, linter, type_checker, git\n- Language/tool extraction and target analysis comparison\n- Directory path matching against scan tree\n- `agentskill/lib/reference_questions.py` — gap detection and targeted question generation\n- `ReferenceQuestion` model with section, question, reason, category, source, blocking, options\n- `generate_reference_questions()` — produce targeted questions from uncertain and mismatched conventions\n- Selective question generation: irrelevant mismatches filtered, ecosystem-aware relevance checks\n- Conflict detection across multiple references proposing different conventions\n- Question deduplication and deterministic ordering\n- `agentskill/lib/reference_initialization.py` — empty-project initialization from references\n- `is_empty_target()` — detect empty or near-empty target repositories\n- `build_reference_metadata()` — build deterministic metadata from loaded documents\n- `render_reference_metadata_block()` — render metadata as Markdown HTML comment with JSON\n- `ReferenceInitializationResult` — structured result with adapted references, questions, metadata, warnings\n- `initialize_from_references()` — end-to-end initialization flow\n- `successful_reference_documents()` — filter load results to successful documents\n- `AGENTSKILL_VERSION` constant\n\n## [0.4.0] - 2026-04-27\n\n### Added\n\n- `agentskill/lib/parsers.py` — shared TOML and YAML parser loading with optional dependency fallback\n- `load_toml` / `load_yaml` — strict parsers that raise `ParserUnavailableError` when deps are missing\n- `load_toml_safe` / `load_yaml_safe` — graceful parsers returning `{}` on any error\n- Comprehensive config parsing tests with real-world fixtures for Python, JS, Go, and Rust\n\n### Changed\n\n- Replaced custom TOML parsing in `config.py` with `tomllib` / `tomli` via shared parser\n- Replaced custom YAML parsing in `config.py` with `PyYAML` `safe_load` via shared parser\n- Moved `tomli` and `PyYAML` to optional `[parsers]` dependency group\n\n### Removed\n\n- `_parse_toml`, `_parse_toml_value`, `_split_toml_array` — replaced by real TOML parser\n- `_parse_yaml_simple`, `_yaml_scalar` — replaced by real YAML parser\n\n## [0.3.0] - 2026-04-26\n\n### Added\n\n- Logging infrastructure — `agentskill/lib/logging_utils.py` with configurable log level and exception capture\n- Output path validation — `--out` paths are validated; parent directories are created automatically\n- Per-analyzer timeout logging — runner logs when an analyzer exceeds its deadline\n- `write_output` exception handling — captures and logs JSON serialization errors\n\n### Changed\n\n- `_run` in `git.py` now returns stderr alongside stdout, and logs command failures\n- `run_all` logs per-analyzer failures with tracebacks instead of silently swallowing them\n\n## [0.2.0] - 2026-04-26\n\n### Added\n\n- GitHub Actions CI workflows — build, test, verify, and main branch checks\n- `tomli` runtime dependency for Python < 3.11 TOML support\n\n### Changed\n\n- Bumped minimum Python version to 3.10\n- Switched build backend to `setuptools.build_meta`\n- Expanded `py-modules` to include `cli` for correct CLI invocation\n\n### Fixed\n\n- Import order error flagged by ruff\n- CLI invocation error caused by missing `py-modules` declaration\n\n## [0.1.0] - 2026-04-26\n\n### Added\n\n- Initial release of agentskill\n- `analyze` command — run all analyzers and synthesize an `AGENTS.md` report\n- `scan` analyzer — directory tree mapping, file inventory, suggested read order\n- `measure` analyzer — exact indentation, line length percentiles, blank line distributions\n- `config` analyzer — formatter, linter, and type-checker detection with config excerpts\n- `git` analyzer — commit prefixes, branch naming, merge strategy, and signing detection\n- `graph` analyzer — internal import graph, circular dependencies, most-depended modules\n- `symbols` analyzer — symbol name extraction, naming pattern clustering, affix detection\n- `tests` analyzer — test-to-source mapping, framework detection, fixture extraction\n- Parallel analyzer execution via `ThreadPoolExecutor`\n- Pretty-printed and machine-readable JSON output modes (`--pretty`, `--json`)\n- `--out` flag to write report to a file\n- `--language` flag to override auto-detected language\n- Language-agnostic analysis engine supporting Python, JavaScript/TypeScript, Rust, Go, and others\n- Multiple output example formats: `SINGLE_LANGUAGE.md`, `MULTI_LANGUAGE.md`, `MONOREPO.md`\n- `SYSTEM.md` — behavioral spec for the synthesis step\n- `SKILL.md` — OpenClaw AgentSkill manifest\n- `AGENTS.md` — self-documented analysis rules\n- Full test suite with pytest covering all modules\n- `pyproject.toml` with `project.scripts` entry points\n- Development dependencies: `ruff`, `pytest`\n\nFile v1.4.0:docs/reference/cli.md\n\n# CLI Reference\n\n## Canonical Entry Point\n\n- Module: `agentskill.main`\n- Published console script: `agentskill = \"agentskill.main:main\"`\n- Primary callable: `main(argv: list[str] | None = None) -> int`\n\n`agentskill.main` is the source of truth for the installed CLI. It owns global\nargument parsing, subcommand registration, and dispatch into analyzer,\ngeneration, and update workflows.\n\n## Public Command Families\n\n- `agentskill analyze [ ...]`\n Runs the full analyzer stack and emits merged JSON.\n- `agentskill scan|measure|config|git|graph|symbols|tests `\n Runs one analyzer and emits that analyzer's JSON payload.\n- `agentskill generate `\n Renders a fresh `AGENTS.md` document to stdout or `--out`.\n- `agentskill update `\n Regenerates sections and merges them into an existing `AGENTS.md`, or creates\n one when missing.\n\n## Dispatch Model\n\n- `cmd_analyze(args)` calls [`agentskill.lib.runner.run_many`](./library.md#runner)\n and writes public JSON through [`agentskill.lib.output.write_output`](./library.md#output-and-schema).\n- `_single_script_cmd(command_name, args)` routes analyzer subcommands through\n the `COMMANDS` registry in `agentskill.lib.runner`.\n- `cmd_generate(args)` delegates to\n [`agentskill.lib.generate_runner.generate_agents`](./library.md#generation-and-update).\n- `cmd_update(args)` delegates to\n [`agentskill.lib.update_runner.update_agents`](./library.md#generation-and-update).\n\n## Flags and Stable Behavior\n\n- `--pretty` applies to JSON-producing analyzer flows only.\n- `--out` writes JSON or markdown to a file instead of stdout.\n- `--reference` is supported by `analyze` and `generate`.\n- `--interactive` is supported by `generate` only.\n- `--profile` is supported by `generate` and `update`. Accepted values are `concise` (default) and `comprehensive`.\n - `concise` emits operational rules and key facts only; representative code snippets and secondary explanatory bullets are suppressed.\n - `comprehensive` includes everything from concise plus representative snippets, annotation measurements, and expanded rationale bullets.\n - All profiles are deterministic from the same analyzer results and preserve the same section order and headings.\n - When `--layout split` is active, the `--profile` flag is ignored: the primary file is always concise and the companion is always comprehensive.\n - When `--layout multifile` is active, `--profile` controls the density of content in each section file. The default profile for multifile is `comprehensive`.\n- `--layout` is supported by `generate`. Accepted values are `single` (default), `split`, and `multifile`.\n - `single` writes one complete markdown file. Without `--out`, prints to stdout.\n - `split` writes two files: a concise primary document and an `AGENTS.reference.md` companion with comprehensive content. The primary file contains a relative link to the companion. Without `--out`, split writes into the target repo using `/AGENTS.md` as the primary path.\n - `multifile` writes a root index file plus per-section markdown files in a `.agentskill/` directory beside the primary output. Section filenames follow a stable numbering scheme: `01_OVERVIEW.md`, `02_REPOSITORY_STRUCTURE.md`, `05_COMMANDS_AND_WORKFLOWS.md`, `06_CODE_FORMATTING.md`, `07_NAMING_CONVENTIONS.md`, `08_TYPE_ANNOTATIONS.md`, `09_IMPORTS.md`, `10_ERROR_HANDLING.md`, `11_COMMENTS_AND_DOCSTRINGS.md`, `12_TESTING.md`, `13_GIT.md`, `14_DEPENDENCIES_AND_TOOLING.md`, `15_RED_LINES.md`. Each section file contains a backlink to the root. Without `--out`, multifile writes into the target repo using `/AGENTS.md` as the root path.\n - `update --layout` is not yet supported for `split` or `multifile` and is explicitly rejected.\n- `--section`, `--exclude-section`, and `--force` are supported by `update`.\n\nRelease-grade CLI contract tests live in `tests/test_cli_contract.py`.\n\nFile v1.4.0:docs/reference/commands.md\n\n# Command Modules\n\nThe analyzer command modules live in `agentskill.commands`. Each module exposes\none primary analyzer callable that accepts a repository path and returns a JSON\nserializable payload, plus a `main()` wrapper for direct execution.\n\n## Inventory\n\n- `agentskill.commands.scan`\n Primary callable: `scan(repo_path: str, lang_filter: str | None = None) -> dict`\n Role: repository walk, file inventory, language summary, and suggested read order.\n- `agentskill.commands.measure`\n Primary callable: `measure(repo_path: str, lang_filter: str | None = None) -> dict`\n Role: formatting metrics such as indentation, line-length percentiles, and blank-line distributions.\n- `agentskill.commands.config`\n Primary callable: `detect(repo_path: str) -> dict`\n Role: formatter, linter, type-checker, build-tool, and project-marker detection.\n- `agentskill.commands.git`\n Primary callable: `analyze(repo_path: str) -> dict`\n Role: commit-prefix, branch-shape, merge-strategy, and repository-history analysis.\n- `agentskill.commands.graph`\n Primary callable: `build_graph(repo_path: str, lang_filter: str | None = None) -> dict`\n Role: import, include, require, and dependency-edge extraction across supported languages.\n- `agentskill.commands.symbols`\n Primary callable: `extract_symbols(repo_path: str, lang_filter: str | None = None) -> dict`\n Role: symbol-name extraction and naming-pattern clustering.\n- `agentskill.commands.tests`\n Primary callable: `analyze_tests(repo_path: str) -> dict`\n Role: test-framework detection, test-to-source mapping, and coverage-shape inference.\n\n## Direct Wrappers\n\nEach analyzer module also exposes `main(argv: list[str] | None = None) -> int`\nfor direct wrapper execution. Those wrappers remain supported under `scripts/`,\nbut they are secondary to the installed `agentskill` CLI.\n\n## Extension Guidance\n\n- Add new analyzer implementation logic inside `agentskill.commands`.\n- Keep analyzer return values JSON-serializable.\n- Follow the error-payload convention used elsewhere in the codebase:\n `{\"error\": \"...\", \"script\": \"\"}`.\n- Wire new public CLI exposure through `agentskill.main`, not by expanding\n wrapper-only behavior under `scripts/`.\n\nFile v1.4.0:docs/reference/common.md\n\n# Common Helpers Reference\n\nThe `agentskill.common` package holds low-level utilities reused across\nanalyzers and library modules.\n\n## Language Registry\n\n- Module: `agentskill.common.languages`\n- Primary helpers:\n `all_language_specs() -> tuple[LanguageSpec, ...]`\n `language_by_id(language_id: str) -> LanguageSpec | None`\n `language_for_extension(extension: str) -> LanguageSpec | None`\n `language_for_path(path: str | Path) -> LanguageSpec | None`\n `is_supported_language(language_id: str) -> bool`\n\nThis registry defines the supported language matrix, filename extensions,\npackage/config markers, test patterns, and source-root hints used throughout\nthe analyzer stack.\n\n## Filesystem Helpers\n\n- Module: `agentskill.common.fs`\n- Primary helpers:\n `validate_repo(path: str) -> Path`\n `read_text(path: Path, max_bytes: int | None = MAX_FILE_BYTES) -> str`\n `count_lines(path: Path) -> int`\n\nThese helpers provide repo-path validation and tolerant file reads for analyzer\nwork that must keep going across partially broken or unusual repositories.\n\n## Repository Walking and Constants\n\n- Module: `agentskill.common.walk`\n Role: repository traversal and file filtering helpers used by analyzers.\n- Module: `agentskill.common.constants`\n Role: shared constants such as byte limits and skip lists.\n\nKeep new low-level helpers here only when they are genuinely reusable across\nmultiple analyzers or library modules. Orchestration-level behavior belongs in\n`agentskill.lib` instead.\n\nFile v1.4.0:docs/reference/library.md\n\n# Library Reference\n\nThe `agentskill.lib` package contains orchestration and document-generation\nhelpers that sit above the analyzer implementations.\n\n## Runner\n\n- Module: `agentskill.lib.runner`\n- Primary callables:\n `run_all(repo: str, lang_filter: str | None = None, references: list[str] | None = None) -> dict`\n `run_many(repos: list[str], lang_filter: str | None = None, references: list[str] | None = None) -> dict`\n\nThis module owns the analyzer registry (`COMMANDS`), parallel analyzer\nexecution, timeout handling, and multi-repo aggregation.\n\n## Output and Schema\n\n- Module: `agentskill.lib.output`\n Primary helpers: `write_output(...)`, `run_and_output(...)`, `validate_out_path(...)`\n- Module: `agentskill.lib.output_schema`\n Primary helper: `validate_public_output(data: object, *, mode: str) -> None`\n\nThese modules validate and serialize public JSON output, enforce `--out` path\nrules, and keep the CLI-facing output contract consistent.\n\n## Generation and Update\n\n- Module: `agentskill.lib.generate_runner`\n Primary callables:\n `render_agents_markdown(...) -> str`\n `generate_agents(...) -> int`\n- Module: `agentskill.lib.update_runner`\n Primary callables:\n `render_agents_sections(...) -> dict[str, AgentsSection]`\n `update_agents(...) -> int`\n- Module: `agentskill.lib.update_merge`\n Primary helper: `merge_agents_document(...)`\n- Module: `agentskill.lib.update_feedback`\n Primary helper: `load_feedback(repo_path: str | Path) -> UpdateFeedback`\n- Module: `agentskill.lib.output_profiles`\n Primary callables: `validate_output_profile(profile: str) -> str`\n Constants: `DEFAULT_OUTPUT_PROFILE`, `SUPPORTED_OUTPUT_PROFILES`\n- Module: `agentskill.lib.output_layouts`\n Primary callables: `validate_output_layout(layout: str) -> str`\n Constants: `DEFAULT_OUTPUT_LAYOUT`, `SUPPORTED_OUTPUT_LAYOUTS`\n- Module: `agentskill.lib.profile_rendering`\n Primary callables: `combine_section_body(...)`, `build_companion_document(...)`, `inject_split_link(...)`, `companion_path(...)`, `companion_relative_link(...)`\n- Module: `agentskill.lib.multifile_output`\n Primary callables: `section_file_path(...)`, `build_section_file(...)`, `build_root_index(...)`\n Constants: `SECTION_FILE_MAP`, `SECTION_DESCRIPTIONS`, `SECTION_DIR`\n\n`generate_runner` produces a fresh document without merge semantics.\n`update_runner` regenerates sections and merges them into an existing\n`AGENTS.md` unless `--force` requests a clean rebuild.\n\nProfile and layout handling: `--profile` controls content density (`concise`\nor `comprehensive`). `--layout` controls output packaging (`single`, `split`,\nor `multifile`). Split layout writes a concise primary plus comprehensive\ncompanion regardless of the profile flag. Multifile layout writes a root\nindex plus per-section files using the specified profile (default\n`comprehensive`).\n\n## Reference and Interactive Flows\n\n- Module: `agentskill.lib.reference_flow`\n Primary helper: `load_reference_documents(references: list[str] | None) -> list[ReferenceDocument]`\n- Module: `agentskill.lib.reference_initialization`\n Primary helper: `initialize_from_references(...)`\n- Module: `agentskill.lib.reference_adaptation`\n Role: compare reference conventions against target analysis signals\n- Module: `agentskill.lib.reference_questions`\n Role: generate follow-up questions when references and target analysis diverge\n- Module: `agentskill.lib.references`\n Role: local and remote reference loading\n- Module: `agentskill.lib.interactive_runner`\n Role: prompt orchestration and interactive-note injection\n\nThese modules power `--reference` and `--interactive` behavior for the packaged\ngeneration flow.\n\n## Other Shared Helpers\n\n- `agentskill.lib.cli_entrypoint`\n Shared analyzer-wrapper argument parsing for direct script entrypoints.\n- `agentskill.lib.logging_utils`\n Stderr logger setup for internal use.\n- `agentskill.lib.parsers`\n Safe TOML and YAML parsing helpers.\n- `agentskill.lib.agents_document`\n AGENTS section parsing and section-object helpers.\n\nFile v1.4.0:skill-card.md\n\n## Description:\n\nLet any agent produce code indistinguishable from the existing codebase.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[airscripts](https://clawhub.ai/user/airscripts)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineers use Agentskill to analyze repositories and produce AGENTS.md guidance that helps coding agents match the target codebase's structure, conventions, workflows, and review expectations.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill inspects repositories named by the user, which can expose local project structure and source conventions to the active agent workflow.\n\nMitigation: Use it only on repositories you are comfortable having the agent inspect, and review the generated AGENTS.md before sharing it.\n\nRisk: User-supplied remote references can influence the generated guidance.\n\nMitigation: Use remote references only from trusted sources and review any imported conventions before adopting the output.\n\nRisk: Generated AGENTS.md guidance can be incorrect or too broad for the repository if evidence is incomplete.\n\nMitigation: Review the draft against the repository before relying on it for coding-agent behavior.\n\n## Reference(s):\n\n- [Agentskill ClawHub listing](https://clawhub.ai/airscripts/skills/agentskill)\n- [Agentskill package on PyPI](https://pypi.org/project/agsk)\n- [Turning Repository Knowledge Into Usable Agent Context](https://dev.to/airscript/turning-repository-knowledge-into-usable-agent-context-4pe4)\n- [API Reference](docs/reference/README.md)\n- [CLI Reference](docs/reference/cli.md)\n- [Generation Gotchas](references/GOTCHAS.md)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Guidance, Shell commands, Configuration]\n\n**Output Format:** [Markdown AGENTS.md documentation, with optional split or multifile markdown layouts.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Skill mode authors AGENTS.md from analyzer evidence; CLI mode can emit deterministic markdown directly.]\n\n## Skill Version(s):\n\n1.4.0 (source: server release evidence, pyproject.toml, CHANGELOG)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.3.0: 49 files, 98629 bytes\n\nFiles: agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (20065b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan.py (3823b), agentskill/commands/symbols.py (38076b), agentskill/commands/tests.py (48210b), agentskill/common/__init__.py (56b), agentskill/common/constants.py (736b), agentskill/common/fs.py (944b), agentskill/common/languages.py (8064b), agentskill/common/walk.py (1764b), agentskill/lib/__init__.py (63b), agentskill/lib/agents_document.py (4904b), agentskill/lib/cli_entrypoint.py (990b), agentskill/lib/generate_runner.py (3072b), agentskill/lib/interactive_runner.py (5621b), agentskill/lib/logging_utils.py (808b), agentskill/lib/output_schema.py (3533b), agentskill/lib/output.py (1829b), agentskill/lib/parsers.py (2381b), agentskill/lib/reference_adaptation.py (10884b), agentskill/lib/reference_flow.py (2127b), agentskill/lib/reference_initialization.py (3403b), agentskill/lib/reference_questions.py (14787b), agentskill/lib/references.py (6923b), agentskill/lib/runner.py (4059b), agentskill/lib/update_feedback.py (4099b), agentskill/lib/update_merge.py (6408b), agentskill/lib/update_runner.py (35008b), agentskill/main.py (6548b), pyproject.toml (1395b), README.md (18160b), references/GOTCHAS.md (8849b), scripts/analyze.py (293b), scripts/config.py (278b), scripts/generate.py (294b), scripts/git.py (275b), scripts/graph.py (277b), scripts/measure.py (279b), scripts/scan.py (276b), scripts/symbols.py (279b), scripts/tests.py (277b), scripts/update.py (292b), SKILL.md (14433b), SYSTEM.md (18227b), _meta.json (129b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: agentskill\ndescription: Analyze a code repository and synthesize an AGENTS.md.\n---\n\n# SKILL.md — agentskill\n\n> **Operational spec for agentskill.**\n> This file governs _when_ to invoke, _what_ to run, and _in what order_.\n> For _how_ to generate `AGENTS.md`, read [`SYSTEM.md`](./SYSTEM.md) — it is the behavioral bible.\n> These two files are complementary. Neither is sufficient alone.\n\n---\n\n## Purpose\n\nAnalyze one or more code repositories. Extract exact coding conventions. Synthesize a precise, forensic `AGENTS.md` that allows any agent to produce code indistinguishable from the existing codebase.\n\n---\n\n## Trigger Phrases\n\nInvoke this skill when the user says any of the following — or a close paraphrase:\n\n- _\"Generate an AGENTS.md\"_\n- _\"Extract my coding style\"_\n- _\"Analyze my repo for conventions\"_\n- _\"Create a style guide from my code\"_\n- _\"Update my AGENTS.md\"_\n- _\"My agent doesn't write code the way I do — fix it\"_\n\nDo **not** invoke this skill for general code review, refactoring, or style advice not tied to generating `AGENTS.md`.\n\n---\n\n## File Ecosystem\n\n| File | Role |\n| ------------------------ | -------------------------------------------------------------------------------------- |\n| `SKILL.md` _(this file)_ | Operational spec: workflow, scripts, fallbacks, uncertainty handling |\n| `SYSTEM.md` | Behavioral spec: what to generate, section by section, and how to evaluate it |\n| `references/GOTCHAS.md` | Extraction errors to avoid; update this file whenever a new failure mode is discovered |\n| `examples/` | Analyzer fixtures plus reference `AGENTS.md` examples; consult when handling an unfamiliar repo shape |\n\n> **Maintenance rule:** If SYSTEM.md and SKILL.md ever contradict each other, SYSTEM.md wins. Fix SKILL.md to match.\n\n> **Availability rule:** If this skill was downloaded from ClawHub, or if `examples/` is unavailable locally, do not consult `examples/`; skip it to avoid execution errors.\n\n---\n\n## Workflow\n\nExecute these steps **in order**. Do not skip steps. Do not reorder steps.\n\n---\n\n### Step 1 — Collect\n\nAsk the user for repo path(s). Accept one or more. Confirm before proceeding.\n\n```\nProvide the path(s) to your repository or repositories.\nOne path per repo. Multiple repos are supported.\n```\n\nIf the user provides a monorepo, note this explicitly — steps 3 and 4 of SYSTEM.md apply.\n\n---\n\n### Step 2 — Scan\n\nRun the scan script to get the directory tree and source file inventory.\n\n```bash\npython scripts/scan.py \n```\n\n**Outputs:** annotated directory tree, source files grouped by language with line counts.\n\n**Use the output to decide what to read** — largest files first, entry points and core modules before tests.\n\n> **If the script fails:** Manually walk the directory tree using available file tools. Note in your working context that the scan was manual — this affects reliability of the file inventory for large repos.\n\n---\n\n### Step 3 — Measure\n\nRun the measurement script to get exact formatting metrics.\n\n```bash\npython scripts/measure.py \npython scripts/measure.py --lang python # single language\n```\n\n**Outputs:** per-language indentation unit and size, line length percentiles (p95 and p99), blank line distributions between top-level definitions and between methods, trailing newline convention.\n\n> **If the script fails:** Proceed without exact measurements. Mark all formatting measurements in the generated `AGENTS.md` as `[tentative]` and note that manual inspection was used. Do not estimate percentiles — state the observable range instead.\n\n---\n\n### Step 4 — Config\n\nRun the config script to detect formatters, linters, and their exact settings.\n\n```bash\npython scripts/config.py \n```\n\n**Outputs:** per-language tool detection with relevant config excerpts — `[tool.black]`, `[tool.ruff]`, `[tool.mypy]`, `tsconfig.json`, `.prettierrc`, `.editorconfig`, and equivalents.\n\n> **If the script fails:** Read config files directly from disk. Prioritize: `pyproject.toml`, `package.json`, `.editorconfig`, any `.*rc` files at the repo root. Do not guess what a formatter enforces — only document what you can read from config.\n\n---\n\n### Step 5 — Read SYSTEM.md\n\n**Read [`SYSTEM.md`](./SYSTEM.md) fully before writing a single line of `AGENTS.md`.**\n\nDo not rely on memory of previous runs. Read it fresh every time.\n\n---\n\n### Step 6 — Read Source Files\n\nRead actual source files directly. Use the file inventory from Step 2 to choose what to read.\n\n**Minimum per language before drafting any section:**\n\n| Priority | What to read |\n| -------- | ----------------------------------------------------------------------- |\n| 1st | Entry point and CLI files |\n| 2nd | Core logic modules (largest non-test files) |\n| 3rd | At least one test file |\n| 4th | Package manifest (`pyproject.toml`, `Cargo.toml`, `package.json`, etc.) |\n| 5th | At least one utility or helper module |\n\n**Minimum count:** 3–5 files per language. For monorepos, 3–5 files per service.\n\nDo not begin drafting until this step is complete.\n\n---\n\n### Step 7 — Check GOTCHAS.md\n\nRead [`references/GOTCHAS.md`](./references/GOTCHAS.md) before drafting.\n\nThis file contains extraction and synthesis errors discovered from previous agentskill runs — false patterns, formatter assumption traps, monorepo boundary mistakes, and section omissions.\n\n---\n\n### Step 8 — Consult Examples\n\nRead the relevant file in [`examples/`](./examples/) if you are handling an unfamiliar repo shape.\n\nIf this skill was downloaded from ClawHub, or if `examples/` is unavailable locally, skip this step to avoid execution errors.\n\n| Scenario | File to consult |\n| ------------------------------- | ----------------------------- |\n| Standard single-language repo | `examples/SINGLE_LANGUAGE.md` |\n| Monorepo with multiple services | `examples/MONOREPO.md` |\n| Multi-language single repo | `examples/MULTI_LANGUAGE.md` |\n\n> **If no relevant example exists:** Proceed without one. Do not consult an example from a different repo shape — it will introduce structural assumptions that don't apply.\n\n---\n\n### Step 9 — Synthesize\n\nFollow SYSTEM.md **section by section**, in the exact order specified.\n\n**Source of truth per data type:**\n\n| Data type | Source |\n| ------------------------------------------- | -------------------------------------- |\n| Line length, indentation, blank line counts | Script output from Step 3 |\n| Formatter and linter settings | Script output from Step 4 |\n| Naming conventions | Direct source file reads (Step 6) |\n| Error handling patterns | Direct source file reads (Step 6) |\n| Import ordering | Direct source file reads (Step 6) |\n| Comment and docstring style | Direct source file reads (Step 6) |\n| Test patterns | Direct source file reads (Step 6) |\n| Directory structure | Script output from Step 2 |\n| Git conventions | `.git/` config + commit log inspection |\n\nFor qualitative sections such as naming, imports, error handling, comments, and testing, enrich from static source evidence first: concrete rules plus real snippets. Use analyzer output to find candidate files, not as the section body.\n\nApply the **Mimicry Test** from SYSTEM.md to each section before moving to the next. Do not batch-test at the end.\n\n---\n\n### Step 10 — Handle Uncertainty\n\nWhen you are uncertain about a pattern mid-synthesis, apply this decision tree — do not silently guess:\n\n```\nIs the pattern supported by fewer than 3 examples?\n YES → Mark the rule [tentative] and continue.\n\nIs there genuine inconsistency with no dominant pattern?\n YES → State the inconsistency explicitly. Do not invent a rule.\n\nIs an entire section unmeasurable (e.g. script failed, files unreadable)?\n YES → Surface this to the user before writing that section.\n Ask: \"I couldn't reliably extract [section].\n Do you want me to skip it, mark it tentative, or provide the data manually?\"\n\nIs the uncertainty minor and isolated to one sub-rule?\n YES → Mark [tentative], continue, note it in the draft summary.\n```\n\n**Never silently guess. Never invent a rule. Never omit a section without telling the user.**\n\n---\n\n### Step 11 — Write\n\nWrite the final `AGENTS.md` to the repo root.\n\n**If this is a new file:** Write directly.\n\n**If an existing `AGENTS.md` is present:**\n\n1. Read the existing file first.\n2. Present a diff-style summary of what will change and why.\n3. Ask for confirmation before overwriting.\n\nAfter writing, output a brief summary:\n\n```\nAGENTS.md written.\n\nSections completed: 15 / 15\nTentative rules: [list them, or \"none\"]\nSections with gaps: [list them, or \"none\"]\nRecommended follow-up: [e.g. \"Run measure.py — line length marked tentative\"]\n```\n\n---\n\n## Why Seven Scripts?\n\nThe scripts handle exactly and only what an LLM cannot do reliably from reading source files.\n\n| Script | Why it cannot be skipped |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `scan.py` | Large repos exceed the context window; without a file inventory the agent reads arbitrarily, missing dominant patterns in unread files |\n| `measure.py` | 95th-percentile line length requires counting every line across every file — estimation from reading samples is structurally inaccurate |\n| `config.py` | Formatter config files are ground truth; inferring what a formatter enforces from its output is unreliable and will drift as config changes |\n| `git.py` | Commit log and branch history require `git log` access; source files alone do not reveal prefix conventions or merge strategy |\n| `graph.py` | Import graph cycle detection and monorepo boundary identification require traversing all files simultaneously, not reading them one by one |\n| `symbols.py` | Codebase-specific affix detection requires counting patterns across every identifier in the repo — impractical to do by reading samples |\n| `tests.py` | Test-to-source mapping and framework detection require walking the full file tree; sampling misses coverage gaps and naming inconsistencies |\n\nEverything else — error handling patterns, comment style, docstring format, architectural rules — comes from reading source files directly. Do not run scripts for things you can read.\n\n---\n\n## Scripts Quick Reference\n\nAll scripts require Python stdlib only. No installation needed beyond `pip install -e .`.\n\n```bash\n# Aggregate analyzer wrapper\npython scripts/analyze.py \n\n# Directory tree and file inventory\npython scripts/scan.py \n\n# Formatting metrics (indentation, line length, blank lines, newlines)\npython scripts/measure.py \npython scripts/measure.py --lang python\n\n# Formatter and linter detection with config excerpts\npython scripts/config.py \n\n# Commit log, branch naming, and merge strategy\npython scripts/git.py \n\n# Internal import graph, cycle detection, monorepo boundaries\npython scripts/graph.py \n\n# Symbol name extraction and codebase-specific affix detection\npython scripts/symbols.py \n\n# Test-to-source mapping, framework detection, fixture extraction\npython scripts/tests.py \n\n# Fresh AGENTS.md draft\npython scripts/generate.py \n\n# Update or create AGENTS.md in place\npython scripts/update.py \n\n# Run all seven analyzers in parallel and merge output\nagentskill analyze --pretty\n```\n\nAll scripts output JSON to stdout. Pass `--pretty` for human-readable output. Pass `--out ` to write to disk.\n\n---\n\n## Uncertainty Reference\n\n| Situation | Action |\n| ------------------------------------------ | ------------------------------------------------------------------------- |\n| Fewer than 3 examples for a rule | Mark `[tentative]` |\n| Genuine inconsistency, no dominant pattern | State the inconsistency; do not invent a rule |\n| Script failed, measurement unavailable | Mark affected measurements `[tentative]`; note manual inspection was used |\n| Entire section unmeasurable | Surface to user; ask before proceeding |\n| Existing `AGENTS.md` present | Diff and confirm before overwriting |\n| No matching example in `examples/` | Skip Step 8; do not use a mismatched example |\n\n---\n\n## Principles\n\n> These are reminders, not the full spec. The full spec is in SYSTEM.md.\n\n- **Extract, don't guess.** Every rule must be grounded in observed code.\n- **Snippets are the spec.** Every non-trivial rule needs a real code snippet.\n- **Static enrichment beats metric summaries.** Qualitative sections should read like observed code behavior, not analyzer tallies.\n- **3 examples minimum.** Fewer → `[tentative]`. Inconsistency → state it.\n- **Scope every rule.** Repo-wide vs. per-language vs. per-service — always explicit.\n- **No statistics in output.** No counts, percentages, or confidence levels in `AGENTS.md`.\n- **Mimicry test per section.** Apply it before moving on, not at the end.\n- **Uncertainty surfaces up.** Never silently guess. Never silently omit.\n\n---\n\n_Update `references/GOTCHAS.md` after every run where a new failure mode is discovered._\n_Update this file whenever the workflow changes._\n_If this file and SYSTEM.md contradict — SYSTEM.md wins._\n\nFile v1.3.0:README.md\n\n# agentskill\n\n[![Main](https://github.com/airscripts/agentskill/actions/workflows/main.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/main.yml)\n[![Release](https://github.com/airscripts/agentskill/actions/workflows/release.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/release.yml)\n\nAnalyze a code repository and synthesize an `AGENTS.md` that lets any agent produce code indistinguishable from the existing codebase.\n\n

\n \"agentskill\"\n

\n\n---\n\n## Table of Contents\n\n- [What It Does](#what-it-does)\n- [How It Works](#how-it-works)\n- [Supported Languages](#supported-languages)\n- [Generation Modes](#generation-modes)\n- [Install](#install)\n- [Development Checks](#development-checks)\n- [Usage](#usage)\n- [Repository Structure](#repository-structure)\n- [Where Code Goes](#where-code-goes)\n- [Developer Workflow](#developer-workflow)\n- [File Ecosystem](#file-ecosystem)\n- [Examples](#examples)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Support](#support)\n- [License](#license)\n\n---\n\n## What It Does\n\nagentskill is not a linter and not a style guide generator. It is a forensic extraction tool. It walks a repository, measures every line, reads every config file, and inspects the commit log — then synthesizes a precise behavioral spec for a code-generating agent.\n\nThe output is not advice. It is mimicry instructions.\n\n---\n\n## How It Works\n\nSeven analyzers run in parallel. Each extracts one class of signal that an LLM cannot derive reliably from reading source files alone:\n\n| Analyzer | What it measures |\n| --------- | ------------------------------------------------------------------- |\n| `scan` | Directory tree, file inventory, suggested read order |\n| `measure` | Exact indentation, line length percentiles, blank line distributions |\n| `config` | Formatter, linter, and type-checker detection with config excerpts |\n| `git` | Commit prefixes, branch naming, merge strategy, signing |\n| `graph` | Internal import graph, circular dependencies, most-depended modules |\n| `symbols` | Symbol name extraction, naming pattern clustering, affix detection |\n| `tests` | Test-to-source mapping, framework detection, fixture extraction |\n\nAnalyzer output feeds directly into `AGENTS.md` synthesis. The synthesis step follows the behavioral spec in [`SYSTEM.md`](./SYSTEM.md).\n\n---\n\n## Supported Languages\n\nagentskill already ships analyzer coverage and repository examples across a\nwide set of languages. This matters because the tool is meant to extract\nproject-specific conventions from real repositories, not only from Python-only\nlayouts.\n\nCurrent supported language set:\n\n- Python\n- TypeScript\n- JavaScript\n- Go\n- Rust\n- Java\n- Kotlin\n- C#\n- C\n- C++\n- Ruby\n- PHP\n- Swift\n- Objective-C\n- Shell / Bash\n\nThe repository also includes fixture/example projects for these languages under\n[`examples/`](./examples/), which act as both regression coverage and reference\nshapes for multi-language analysis.\n\n---\n\n## Generation Modes\n\nagentskill supports two complementary generation workflows:\n\n### Static Generation\n\nUse the CLI when you want deterministic output based on analyzer results plus\nstatic source inspection.\n\n- `agentskill analyze --pretty` for combined machine-readable analysis\n- `agentskill generate ` for a fresh `AGENTS.md` draft\n- `agentskill update ` for deterministic regeneration of an existing\n `AGENTS.md`\n\nThis is the default mode for users who want a direct tool-driven workflow\nwithout relying on an external agent harness.\n\n### Artificial Generation\n\nThis repository is also distributed as a dedicated skill through the repo-root\n[`SKILL.md`](./SKILL.md). In that mode, an agent harness can install the skill,\nfollow the skill workflow, and use the same analyzers plus the richer\nskill/system instructions to synthesize or update `AGENTS.md`.\n\nIn short:\n\n- use the CLI for basic static generation,\n- use the skill for agent-assisted or marketplace-installed generation.\n\n---\n\n## Install\n\n```bash\npip install agsk\n```\n\nThis installs the `agentskill` CLI command.\n\nPublished package is available at:\n\n- PyPI: \n- ClawHub: \n\nFor local development:\n\n```bash\npython -m pip install -e '.[dev]'\n```\n\nTo enable the commit-time checks after installing the dev environment:\n\n```bash\npre-commit install\n```\n\n### For Agents\n\nThis repository is also distributed as a standard skill with a repo-root\n`SKILL.md`. Harnesses that support skill installation from a filesystem path,\ngit repository, or marketplace entry should install it as a normal skill and\nuse `SKILL.md` as the entrypoint document.\n\nGeneric install guidance for skill-aware harnesses:\n\n- If the harness installs skills from a local path, point it at the repository\n root so it can read `SKILL.md`, `SYSTEM.md`, `references/`, and `examples/`.\n- If the harness installs skills from a git repository, use this repository URL\n and keep the repo-root `SKILL.md` as the skill manifest.\n- If the harness installs skills from a marketplace, use the ClawHub entry:\n .\n- If the harness only needs the CLI and not the skill manifest, install the\n PyPI package instead: .\n\nExpected skill layout:\n\n```text\nSKILL.md # skill entrypoint and workflow\nSYSTEM.md # generation/synthesis behavioral spec\nreferences/ # gotchas and supporting guidance\nexamples/ # fixture repos and reference shapes\n```\n\nAfter a harness installs the skill, the usual operator-facing commands remain:\n\n```bash\nagentskill analyze --pretty\nagentskill generate \nagentskill update \n```\n\n---\n\n## Development Checks\n\nRun the canonical local checks:\n\n```bash\nruff format .\nruff check .\nmypy\npytest\n```\n\nTo verify formatting without rewriting files:\n\n```bash\nruff format --check .\nruff check .\nmypy\npytest\n```\n\n`mypy` is the repo's configured type-check command. Its configuration in\n`pyproject.toml` covers `agentskill/`, `scripts/`, and `tests/`.\n\nOptional commit-time hooks are available if you want them locally:\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\nThe pre-commit setup mirrors the lightweight formatting, lint, and type-check\npasses. Full `pytest` runs remain part of normal local verification and CI.\n\n---\n\n## Usage\n\n```bash\n# Canonical installed CLI\nagentskill analyze --pretty\nagentskill scan --pretty\nagentskill measure --lang python --pretty\nagentskill config --pretty\nagentskill git --pretty\nagentskill graph --pretty\nagentskill symbols --pretty\nagentskill tests --pretty\n\n# Write output to file\nagentskill analyze --out report.json\nagentskill analyze --reference ../reference-repo --pretty\n\n# Generate AGENTS.md markdown directly\nagentskill generate \nagentskill generate --out AGENTS.md\nagentskill generate --reference ../ref-a --reference ../ref-b\nagentskill generate --interactive\n\n# Update or create AGENTS.md in place\nagentskill update \nagentskill update --section testing\nagentskill update --exclude-section git\nagentskill update --force\nagentskill update --out updated-AGENTS.md\n\n# Retained wrapper entrypoints for operator/skill workflows\npython scripts/analyze.py --pretty\npython scripts/scan.py --pretty\npython scripts/measure.py --lang python --pretty\npython scripts/generate.py \npython scripts/update.py \n```\n\nThe installed `agentskill` command is the steady-state CLI surface, including\nlocal development after an editable install. The retained `scripts/*.py`\nwrappers exist for direct analyzer execution and skill/operator workflows; they\nare not the primary runtime surface.\n\nThe published console entrypoint is `agentskill.main:main`. The packaged\nruntime under `agentskill/` is the source of truth for subcommand behavior,\noutput contracts, generation, update flows, and reference handling.\n\n### Choosing `analyze`, `generate`, or `update`\n\nUse `analyze` when you want machine-readable JSON from all analyzers and do not\nwant to touch any markdown files. This is the contract-stable inspection path.\n\nUse `generate` when you want a fresh AGENTS draft from current analyzer output.\nIt prints markdown to stdout by default, never merges with an existing\n`AGENTS.md`, and only writes a file when you pass `--out`.\n\nUse `update` when you already have an `AGENTS.md` and want deterministic\nregeneration plus preservation of untouched manual content. It writes back to\n`/AGENTS.md` by default, or to `--out` while still using the repo-local\n`AGENTS.md` as merge input.\n\n### Reference Workflow\n\nBoth `analyze` and `generate` accept repeatable `--reference` flags. References\nare explicit inputs, not hidden priors.\n\n- Every local reference must point to a directory with a readable `AGENTS.md`.\n- Duplicate references are rejected instead of being silently counted twice.\n- `analyze --reference` validates references but does not change the JSON output\n shape.\n- `generate --reference` preserves reference order in the emitted metadata block\n so the provenance is inspectable.\n\n### Interactive Generation\n\n`generate --interactive` is opt-in guided gap filling. It asks a small number of\ntargeted questions only when important signals are missing or ambiguous, then\ninjects those answers into the generated markdown as explicit interactive notes.\n\nReferences can reduce prompt count when they clearly provide the missing\nconvention. Conflicting references do not get auto-resolved; the command asks\ninstead of guessing.\n\n### Update Workflow\n\n`agentskill update ` analyzes the repository, regenerates AGENTS sections,\nmerges them with any existing `AGENTS.md`, and writes the result back to\n`/AGENTS.md` by default.\n\n- Use `--section` to regenerate only named sections.\n- Use `--exclude-section` to keep generated sections untouched.\n- Missing targeted sections are inserted without rewriting unrelated manual\n sections.\n- Untouched custom sections and preamble text stay in place in normal mode.\n- Use `--force` for a clean-slate rebuild that drops preserved/manual sections\n and ignores preservation hints from feedback.\n\n### Repo-Local Feedback\n\nIncremental updates can read an optional repo-local sidecar file named\n`.agentskill-feedback.json`. This file is explicit, version-controllable, and\naffects only the current repository. It is not hidden memory and it is not\nglobal learning.\n\n```json\n{\n \"sections\": {\n \"overview\": {\n \"prepend_notes\": [\n \"Mention that deployments go through GitHub Actions.\"\n ]\n },\n \"testing\": {\n \"pinned_facts\": [\n \"Use pytest as the canonical test runner.\"\n ]\n }\n },\n \"preserve_sections\": [\n \"red lines\"\n ]\n}\n```\n\nSupported feedback keys are intentionally narrow by design:\n\n- `sections..prepend_notes`\n- `sections..pinned_facts`\n- `preserve_sections`\n\nIn normal update mode, `preserve_sections` acts like an implicit exclusion list.\nIn `--force` mode, those preservation hints are ignored so the command can\nproduce a true clean-slate rebuild.\n\nUse `.agentskill-feedback.json` when you want durable, repo-local regeneration\nguidance that should survive future updates. Edit `AGENTS.md` directly when you\nare making one-off manual notes that should remain untouched unless you\nexplicitly target or force-regenerate that section.\n\n---\n\n## Repository Structure\n\n```\nREADME.md # user-facing overview and contributor workflow\nAGENTS.md # conventions for this repository itself\nSYSTEM.md # synthesis spec for generated AGENTS.md files\nSKILL.md # operational workflow used by the skill\npyproject.toml # packaging, CLI entrypoint, tool configuration\nLICENSE\ndocs/\n reference/ # packaged API reference for contributors\nagentskill/\n main.py # packaged CLI entry point — subcommand dispatch only\n commands/ # analyzer implementations\n lib/ # orchestration, output, update, generation helpers\n common/ # shared low-level helpers and registries\nscripts/\n *.py # thin wrappers that import packaged analyzer entrypoints\ntests/ # pytest suite for package code and wrapper behavior\nreferences/\n GOTCHAS.md # extraction and synthesis errors to avoid\nexamples/\n README.md # language fixture index for analyzer validation\n python/ # compact per-language analyzer fixtures\n javascript/\n typescript/\n go/\n rust/\n java/\n kotlin/\n csharp/\n c/\n cpp/\n ruby/\n php/\n swift/\n objectivec/\n bash/\n mixed/\n SINGLE_LANGUAGE.md # reference output: single-language repo\n MULTI_LANGUAGE.md # reference output: multi-language single repo\n MONOREPO.md # reference output: monorepo with multiple services\n```\n\n---\n\n## Where Code Goes\n\n- Put packaged CLI and runtime code in `agentskill/`.\n- Put analyzer implementations in `agentskill/commands/`.\n- Put shared orchestration, generation, update, and output helpers in `agentskill/lib/`.\n- Put reusable low-level helpers and registries in `agentskill/common/`.\n- Keep `scripts/` limited to thin wrappers and operator-facing workflow entrypoints.\n- Do not add analyzer or business logic to `scripts/`.\n- Add tests in `tests/` as `test_.py`; do not colocate tests under `scripts/`.\n- Keep root-level files focused on metadata, docs, and project-wide specs.\n\nThere is no separate steady-state runtime under `scripts/`, and there is no\nroot `cli.py` compatibility entrypoint to extend. New runtime behavior should\nland in the package tree and then be exposed through `agentskill.main` if\nit belongs on the public CLI.\n\n---\n\n## Developer Workflow\n\nFor normal use and contributor verification:\n\n```bash\npython -m pip install -e '.[dev]'\nagentskill analyze --pretty\nruff format .\nruff check .\nmypy\npytest\n```\n\nWhen you add or extend functionality:\n\n- Add analyzer logic in `agentskill/commands/` when it maps to a command.\n- Add shared helpers in `agentskill/lib/` or `agentskill/common/`, based on whether they are orchestration-level or low-level utilities.\n- Wire new CLI behavior through [`agentskill/main.py`](./agentskill/main.py).\n- Add a `scripts/*.py` wrapper only when direct operator or skill invocation is still useful, and keep it as a thin import-and-dispatch shim.\n- Cover both packaged behavior and any retained wrapper behavior in `tests/`.\n\nFor retained wrappers:\n\n- Use `agentskill ...` as the canonical interface in docs and examples.\n- Use `python scripts/.py ...` only for retained thin wrappers that still exist.\n- Keep `generate` and `update` wrappers thin; packaged CLI behavior must still live under `agentskill/`.\n\n---\n\n## File Ecosystem\n\nThree files govern behavior. Read all three before modifying anything.\n\n| File | Role |\n| --------------- | ---------------------------------------------------------------------------------- |\n| `SYSTEM.md` | The canonical spec: what every section of `AGENTS.md` must contain and how to evaluate it |\n| `SKILL.md` | The operational workflow: when to invoke, what scripts to run, in what order |\n| `GOTCHAS.md` | Extraction and synthesis errors from previous runs — read before writing |\n\nThe public commands stay the same after refactors. The packaged runtime lives\nunder `agentskill/`, while `scripts/` stays intentionally small as a\nwrapper and operator layer for direct analyzer entrypoints.\n\n---\n\n## Examples\n\nThe `examples/` directory now serves two roles:\n\n- Compact static language fixtures under per-language subdirectories for analyzer validation.\n- Reference `AGENTS.md` examples in `SINGLE_LANGUAGE.md`, `MULTI_LANGUAGE.md`, and `MONOREPO.md`.\n\nIf this skill was downloaded from ClawHub, or if `examples/` is not present in the local copy, do not consult it; skip that step to avoid execution errors.\n\nSee [`examples/README.md`](./examples/README.md) for the supported fixture set.\n\n---\n\n## API Reference\n\nStatic API reference for the packaged codebase lives under\n[`docs/reference/`](./docs/reference/README.md):\n\n- [`docs/reference/cli.md`](./docs/reference/cli.md) for the packaged CLI entrypoint and dispatch model\n- [`docs/reference/commands.md`](./docs/reference/commands.md) for analyzer command modules\n- [`docs/reference/library.md`](./docs/reference/library.md) for orchestration, generation, update, and reference helpers\n- [`docs/reference/common.md`](./docs/reference/common.md) for low-level registries and filesystem helpers\n\nThe reference is contributor-oriented. It documents the packaged namespace and\nextension points that matter for real maintenance work without trying to expose\nevery private helper as public API.\n\n---\n\n## Contributing\n\nContributions are welcome, especially in these areas:\n\n- improving static `AGENTS.md` generation quality\n- expanding analyzer depth per supported language\n- tightening output contracts and regression coverage\n- improving skill ergonomics for agent harnesses\n\nBefore opening a pull request, read:\n\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md)\n- [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)\n\nUse the repository issue and pull request templates when reporting bugs,\nrequesting features, or proposing changes.\n\n---\n\n## Security\n\nFor supported versions and vulnerability reporting guidance, see\n[`SECURITY.md`](./SECURITY.md).\n\n---\n\n## Support\n\nProject metadata and support files available in this repository include:\n\n- [GitHub Sponsors](https://github.com/sponsors/airscripts)\n- [Ko-Fi](https://ko-fi.com/airscript)\n\nIf you want to support the project, starring, sharing, contributing fixes, and\nsupporting through GitHub Sponsors all help.\n\n---\n\n## License\n\nMIT\n\nFile v1.3.0:_meta.json\n\n{\n \"ownerId\": \"kn74ef8bfstn5pmnv2b2jkc73d85jqdn\",\n \"slug\": \"agentskill\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1777764492527\n}\n\nFile v1.3.0:references/GOTCHAS.md\n\n# GOTCHAS.md — Extraction and Synthesis Errors\n\n> Read this file in full before drafting any section of `AGENTS.md`.\n> Every entry here is a failure mode discovered from an actual run.\n> When you discover a new one, add it.\n\n---\n\n## Extraction Errors\n\nThese errors occur during data collection — the signal is wrong before synthesis even begins.\n\n---\n\n### Keyword pollution\n\n**What happens:** Language keywords (`self`, `cls`, `if`, `for`, `return`) are counted alongside identifier names, inflating snake_case totals and polluting naming pattern analysis.\n\n**Fix:** Filter keywords before classifying names. Do not count anything that appears in the language's reserved word list.\n\n---\n\n### Single-word name ambiguity\n\n**What happens:** A name like `foo` or `data` matches both `camelCase` and `snake_case` classifiers because it has no case transitions. These names dominate short codebases and produce false confidence.\n\n**Fix:** Require at least one case transition or underscore before classifying a name. Single-word names are `other`, not evidence of any convention.\n\n---\n\n### Generated file skew\n\n**What happens:** Vendored files, lockfiles, and generated code have zero comments, uniform indentation, and no meaningful names. Including them distorts every measurement.\n\n**Fix:** Exclude all directories in `SKIP_DIRS` — including `node_modules`, `vendor`, `dist`, `build`, `.eggs`, `site-packages`, and `__pycache__`. Do not include `.lock` files in line length or whitespace analysis.\n\n---\n\n### Test file bias\n\n**What happens:** Test files use different idioms than source files — more `assert` statements, more fixture variables, more repetitive naming. Mixing them into source analysis contaminates naming and error handling measurements.\n\n**Fix:** Analyze test files and source files separately. Only report source-file patterns as codebase conventions. Call out test-specific patterns explicitly under Section 12.\n\n---\n\n### Blank line measurement at file boundaries\n\n**What happens:** The first top-level definition in a file has no predecessor, so the blank line count bef\n\nArchive v1.2.0: 46 files, 97451 bytes\n\nFiles: agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (20065b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan.py (3823b), agentskill/commands/symbols.py (38076b), agentskill/commands/tests.py (48210b), agentskill/common/__init__.py (56b), agentskill/common/constants.py (736b), agentskill/common/fs.py (944b), agentskill/common/languages.py (8064b), agentskill/common/walk.py (1764b), agentskill/lib/__init__.py (63b), agentskill/lib/agents_document.py (4904b), agentskill/lib/cli_entrypoint.py (990b), agentskill/lib/generate_runner.py (3072b), agentskill/lib/interactive_runner.py (5621b), agentskill/lib/logging_utils.py (808b), agentskill/lib/output_schema.py (3533b), agentskill/lib/output.py (1829b), agentskill/lib/parsers.py (2381b), agentskill/lib/reference_adaptation.py (10884b), agentskill/lib/reference_flow.py (2127b), agentskill/lib/reference_initialization.py (3403b), agentskill/lib/reference_questions.py (14787b), agentskill/lib/references.py (6923b), agentskill/lib/runner.py (4059b), agentskill/lib/update_feedback.py (4099b), agentskill/lib/update_merge.py (6408b), agentskill/lib/update_runner.py (35008b), agentskill/main.py (6548b), pyproject.toml (1395b), README.md (17653b), references/GOTCHAS.md (8849b), scripts/config.py (278b), scripts/git.py (275b), scripts/graph.py (277b), scripts/measure.py (279b), scripts/scan.py (276b), scripts/symbols.py (279b), scripts/tests.py (277b), SKILL.md (14230b), SYSTEM.md (18227b), _meta.json (129b)\n\nArchive v1.1.0: 110 files, 180163 bytes\n\nFiles: AGENTS.md (19319b), agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (20065b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan.py (3823b), agentskill/commands/symbols.py (38076b), agentskill/commands/tests.py (48210b), agentskill/common/__init__.py (56b), agentskill/common/constants.py (736b), agentskill/common/fs.py (944b), agentskill/common/languages.py (8064b), agentskill/common/walk.py (1764b), agentskill/lib/__init__.py (63b), agentskill/lib/agents_document.py (4904b), agentskill/lib/cli_entrypoint.py (990b), agentskill/lib/generate_runner.py (3072b), agentskill/lib/interactive_runner.py (5621b), agentskill/lib/logging_utils.py (808b), agentskill/lib/output_schema.py (3533b), agentskill/lib/output.py (1829b), agentskill/lib/parsers.py (2381b), agentskill/lib/reference_adaptation.py (10884b), agentskill/lib/reference_flow.py (2127b), agentskill/lib/reference_initialization.py (3403b), agentskill/lib/reference_questions.py (14787b), agentskill/lib/references.py (6923b), agentskill/lib/runner.py (4059b), agentskill/lib/update_feedback.py (4099b), agentskill/lib/update_merge.py (6408b), agentskill/lib/update_runner.py (35008b), agentskill/main.py (6548b), CHANGELOG.md (15520b), docs/reference/cli.md (1861b), docs/reference/commands.md (2204b), docs/reference/common.md (1488b), docs/reference/library.md (2847b), docs/reference/README.md (934b), pyproject.toml (1395b), README.md (14381b), references/GOTCHAS.md (8849b), scripts/config.py (278b), scripts/git.py (275b), scripts/graph.py (277b), scripts/measure.py (279b), scripts/scan.py (276b), scripts/symbols.py (279b), scripts/tests.py (277b), SKILL.md (14230b), SYSTEM.md (18227b), tests/conftest.py (152b), tests/contract_utils.py (1122b), tests/contracts/analyze_mixed.json (6705b), tests/contracts/analyze_python.json (3964b), tests/contracts/config_mixed.json (267b), tests/contracts/graph_mixed.json (670b), tests/contracts/scan_python.json (436b), tests/contracts/symbols_python.json (937b), tests/fixtures/go/golangci.yml (283b), tests/fixtures/js/eslint.yaml (205b), tests/fixtures/js/prettier.yaml (57b), tests/fixtures/python/pyproject.toml (479b), tests/fixtures/rust/clippy.toml (113b), tests/fixtures/rust/rustfmt.toml (147b), tests/test_agents_document.py (3857b), tests/test_cli_contract.py (10970b), tests/test_cli_entrypoint.py (2164b), tests/test_cli.py (2818b), tests/test_common.py (3304b), tests/test_config.py (17173b), tests/test_docs.py (1918b), tests/test_error_contracts.py (1403b), tests/test_examples.py (8283b), tests/test_generate_cli.py (10015b), tests/test_git.py (6118b), tests/test_go_graph.py (3740b), tests/test_go_symbols.py (2465b), tests/test_go_tests.py (2831b)\n\nArchive v1.0.0: 110 files, 173390 bytes\n\nFiles: AGENTS.md (16702b), agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (20065b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan.py (3823b), agentskill/commands/symbols.py (38076b), agentskill/commands/tests.py (48210b), agentskill/common/__init__.py (56b), agentskill/common/constants.py (736b), agentskill/common/fs.py (944b), agentskill/common/languages.py (8064b), agentskill/common/walk.py (1764b), agentskill/lib/__init__.py (63b), agentskill/lib/agents_document.py (4586b), agentskill/lib/cli_entrypoint.py (990b), agentskill/lib/generate_runner.py (3072b), agentskill/lib/interactive_runner.py (5621b), agentskill/lib/logging_utils.py (808b), agentskill/lib/output_schema.py (3533b), agentskill/lib/output.py (1829b), agentskill/lib/parsers.py (2381b), agentskill/lib/reference_adaptation.py (10884b), agentskill/lib/reference_flow.py (2127b), agentskill/lib/reference_initialization.py (3403b), agentskill/lib/reference_questions.py (14787b), agentskill/lib/references.py (6923b), agentskill/lib/runner.py (4059b), agentskill/lib/update_feedback.py (4099b), agentskill/lib/update_merge.py (6408b), agentskill/lib/update_runner.py (17728b), agentskill/main.py (6548b), CHANGELOG.md (14797b), docs/reference/cli.md (1861b), docs/reference/commands.md (2204b), docs/reference/common.md (1488b), docs/reference/library.md (2847b), docs/reference/README.md (934b), pyproject.toml (1395b), README.md (12917b), references/GOTCHAS.md (8322b), scripts/config.py (278b), scripts/git.py (275b), scripts/graph.py (277b), scripts/measure.py (279b), scripts/scan.py (276b), scripts/symbols.py (279b), scripts/tests.py (277b), SKILL.md (13861b), SYSTEM.md (17694b), tests/conftest.py (152b), tests/contract_utils.py (1122b), tests/contracts/analyze_mixed.json (6705b), tests/contracts/analyze_python.json (3964b), tests/contracts/config_mixed.json (267b), tests/contracts/graph_mixed.json (670b), tests/contracts/scan_python.json (436b), tests/contracts/symbols_python.json (937b), tests/fixtures/go/golangci.yml (283b), tests/fixtures/js/eslint.yaml (205b), tests/fixtures/js/prettier.yaml (57b), tests/fixtures/python/pyproject.toml (479b), tests/fixtures/rust/clippy.toml (113b), tests/fixtures/rust/rustfmt.toml (147b), tests/test_agents_document.py (3372b), tests/test_cli_contract.py (10940b), tests/test_cli_entrypoint.py (2164b), tests/test_cli.py (2818b), tests/test_common.py (3304b), tests/test_config.py (17173b), tests/test_docs.py (1918b), tests/test_error_contracts.py (1403b), tests/test_examples.py (8283b), tests/test_generate_cli.py (9874b), tests/test_git.py (6118b), tests/test_go_graph.py (3740b), tests/test_go_symbols.py (2465b), tests/test_go_tests.py (2831b)\n\nArchive v0.10.0: 102 files, 162134 bytes\n\nFiles: AGENTS.md (16702b), agentskill/__init__.py (56b), agentskill/commands/__init__.py (56b), agentskill/commands/config.py (19200b), agentskill/commands/git.py (8849b), agentskill/commands/graph.py (39190b), agentskill/commands/measure.py (14254b), agentskill/commands/scan...","readmeExcerpt":"Skill: Agentskill Owner: airscripts Summary: Let any agent produce code indistinguishable from the existing codebase. Tags: latest:1.4.0 Version history: v1.4.0 | 2026-05-06T23:16:37.554Z | user Agentskill 1.4.0 - Added explicit distinction between AI-led (skill) and CLI static (operator) generation for AGENTS.md. - Clarified that in skill mode, only analyzer commands are used for evidence; final document is always a","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Provide the path(s) to your repository or repositories.\nOne path per repo. Multiple repos are supported."},{"language":"bash","snippet":"python scripts/scan.py "},{"language":"bash","snippet":"python scripts/measure.py \npython scripts/measure.py --lang python # single language"},{"language":"bash","snippet":"python scripts/config.py "},{"language":"text","snippet":"Which output shape do you want?\nProfile: concise or comprehensive\nLayout: single file, split, or multifile"},{"language":"text","snippet":"Generating: profile=concise, layout=single"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agentskill\ndescription: Let any agent produce code indistinguishable from the existing codebase.\n---\n\n# SKILL.md — agentskill\n\n> **Operational spec for agentskill.**\n> This file governs _when_ to invoke, _what_ to run, and _in what order_.\n> For _how_ to generate `AGENTS.md`, read [`SYSTEM.md`](./SYSTEM.md) — it is the behavioral bible.\n> These two files are complementary. Neither is sufficient alone.\n\n---\n\n## Purpose\n\nAnalyze one or more code repositories. Extract exact coding conventions. Synthesize a precise, forensic `AGENTS.md` that allows any agent to produce code indistinguishable from the existing codebase.\n\n---\n\n## Generation Modes\n\nagentskill supports two generation modes. The mode determines who authors the\nfinal document:\n\n### AI-led generation (skill mode — this file)\n\nThe model synthesizes the final `AGENTS.md` itself. CLI analyzer commands are\nused **only for evidence gathering** — to extract repository facts that the\nmodel cannot derive reliably from reading source files alone.\n\n**In skill mode, never call `agentskill generate` to produce the final\n`AGENTS.md`.** The model is the author. Analyzer output is the raw material,\nnot the finished product.\n\n### CLI static generation (operator mode)\n\nThe user runs `agentskill generate` directly. The packaged runtime emits\nmarkdown automatically. This is appropriate for deterministic direct generation\nwithout an LLM in the loop.\n\n**Use CLI generation only in non-LLM static/operator workflows where the user\nexplicitly wants tool-generated markdown rather than AI-authored synthesis.**\n\n---\n\n## Rule: AI Authorship\n\n> **The model authors the final document in skill mode.**\n\n- Do not use `agentskill generate` or `python scripts/generate.py` to produce\n the final `AGENTS.md` when operating as a skill or in any AI-assisted\n workflow.\n- Use analyzer commands (`analyze`, `scan`, `measure`, `config`, `git`, `graph`,\n `symbols`, `tests`) to gather repository facts.\n- The final generated markdown must be synthesized by the AI from analyzer\n evidence, direct source file reads, and supporting documentation.\n- Treat analyzer outputs as evidence, not as the final authored document.\n\n---\n\n## Trigger Phrases\n\nInvoke this skill when the user says any of the following — or a close paraphrase:\n\n- _\"Generate an AGENTS.md\"_\n- _\"Extract my coding style\"_\n- _\"Analyze my repo for conventions\"_\n- _\"Create a style guide from my code\"_\n- _\"Update my AGENTS.md\"_\n- _\"My agent doesn't write code the way I do — fix it\"_\n\nDo **not** invoke this skill for general code review, refactoring, or style advice not tied to generating `AGENTS.md`.\n\n---\n\n## File Ecosystem\n\n| File | Role |\n| ------------------------ | -------------------------------------------------------------------------------------- |\n| `SKILL.md` _(this file)_ | Operational spec: workflow, scripts, fallbacks, uncertainty handling "},{"path":"docs/reference/README.md","content":"# API Reference\n\nThis directory documents the packaged `agentskill/` namespace as shipped.\n\nThe public CLI surface is the installed `agentskill` command wired through\n`agentskill.main:main`. Analyzer implementations live in `agentskill.commands`,\nshared orchestration and generation/update helpers live in `agentskill.lib`,\nand reusable low-level helpers live in `agentskill.common`.\n\nReference pages:\n\n- [`cli.md`](./cli.md): packaged CLI entrypoint, subcommands, and dispatch\n- [`commands.md`](./commands.md): analyzer command modules and their primary callables\n- [`library.md`](./library.md): orchestration, output, update, generation, and reference helpers\n- [`common.md`](./common.md): shared registries, filesystem helpers, and repository walking utilities\n\nThis reference is intentionally static and release-oriented. It describes the\ncurrent packaged layout and contributor extension points rather than every\nprivate helper."},{"path":"README.md","content":"# agentskill\n\n[![Main](https://github.com/airscripts/agentskill/actions/workflows/main.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/main.yml)\n[![Release](https://github.com/airscripts/agentskill/actions/workflows/release.yml/badge.svg)](https://github.com/airscripts/agentskill/actions/workflows/release.yml)\n![ClawHub](https://skill-history.com/badge/airscripts/agentskill.svg)\n\nAnalyze a code repository and synthesize an `AGENTS.md` that lets any agent produce code indistinguishable from the existing codebase.\n\n

\n \"agentskill\"\n

\n\n---\n\n## Table of Contents\n\n- [What It Does](#what-it-does)\n- [How It Works](#how-it-works)\n- [Supported Languages](#supported-languages)\n- [Generation Modes](#generation-modes)\n- [Install](#install)\n- [Development Checks](#development-checks)\n- [Usage](#usage)\n- [Repository Structure](#repository-structure)\n- [Where Code Goes](#where-code-goes)\n- [Developer Workflow](#developer-workflow)\n- [File Ecosystem](#file-ecosystem)\n- [Examples](#examples)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Statistics](#statistics)\n- [Support](#support)\n- [License](#license)\n\n---\n\n## What It Does\n\nagentskill is not a linter and not a style guide generator. It is a forensic extraction tool. It walks a repository, measures every line, reads every config file, and inspects the commit log — then synthesizes a precise behavioral spec for a code-generating agent.\n\nThe output is not advice. It is mimicry instructions.\n\n---\n\n## How It Works\n\nSeven analyzers run in parallel. Each extracts one class of signal that an LLM cannot derive reliably from reading source files alone:\n\n| Analyzer | What it measures |\n| --------- | ------------------------------------------------------------------- |\n| `scan` | Directory tree, file inventory, suggested read order |\n| `measure` | Exact indentation, line length percentiles, blank line distributions |\n| `config` | Formatter, linter, and type-checker detection with config excerpts |\n| `git` | Commit prefixes, branch naming, merge strategy, signing |\n| `graph` | Internal import graph, circular dependencies, most-depended modules |\n| `symbols` | Symbol name extraction, naming pattern clustering, affix detection |\n| `tests` | Test-to-source mapping, framework detection, fixture extraction |\n\nAnalyzer output feeds directly into `AGENTS.md` synthesis. The synthesis step follows the behavioral spec in [`SYSTEM.md`](./SYSTEM.md).\n\n> Check our latest technical article for a deeper dive:\n> [Turning Repository Knowledge Into Usable Agent Context](https://dev.to/airscript/turning-repository-knowledge-into-usable-agent-context-4pe4).\n\n---\n\n## Supported Languages\n\nagentskill already ships analyzer coverage and repository e"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74ef8bfstn5pmnv2b2jkc73d85jqdn\",\n \"slug\": \"agentskill\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1778109397554\n}"},{"path":"references/GOTCHAS.md","content":"# GOTCHAS.md — Extraction and Synthesis Errors\n\n> Read this file in full before drafting any section of `AGENTS.md`.\n> Every entry here is a failure mode discovered from an actual run.\n> When you discover a new one, add it.\n\n---\n\n## Extraction Errors\n\nThese errors occur during data collection — the signal is wrong before synthesis even begins.\n\n---\n\n### Keyword pollution\n\n**What happens:** Language keywords (`self`, `cls`, `if`, `for`, `return`) are counted alongside identifier names, inflating snake_case totals and polluting naming pattern analysis.\n\n**Fix:** Filter keywords before classifying names. Do not count anything that appears in the language's reserved word list.\n\n---\n\n### Single-word name ambiguity\n\n**What happens:** A name like `foo` or `data` matches both `camelCase` and `snake_case` classifiers because it has no case transitions. These names dominate short codebases and produce false confidence.\n\n**Fix:** Require at least one case transition or underscore before classifying a name. Single-word names are `other`, not evidence of any convention.\n\n---\n\n### Generated file skew\n\n**What happens:** Vendored files, lockfiles, and generated code have zero comments, uniform indentation, and no meaningful names. Including them distorts every measurement.\n\n**Fix:** Exclude all directories in `SKIP_DIRS` — including `node_modules`, `vendor`, `dist`, `build`, `.eggs`, `site-packages`, and `__pycache__`. Do not include `.lock` files in line length or whitespace analysis.\n\n---\n\n### Test file bias\n\n**What happens:** Test files use different idioms than source files — more `assert` statements, more fixture variables, more repetitive naming. Mixing them into source analysis contaminates naming and error handling measurements.\n\n**Fix:** Analyze test files and source files separately. Only report source-file patterns as codebase conventions. Call out test-specific patterns explicitly under Section 12.\n\n---\n\n### Blank line measurement at file boundaries\n\n**What happens:** The first top-level definition in a file has no predecessor, so the blank line count before it is always zero. Including this in the distribution pulls the mode toward zero even when the real convention is two blank lines between definitions.\n\n**Fix:** Exclude the first definition in each file from the blank-line-between-definitions measurement. Only measure gaps _between_ two definitions, never before the first one.\n\n---\n\n### Import misclassification\n\n**What happens:** stdlib module names that overlap with third-party package names (`email`, `ast`, `typing`) get classified as third-party, and vice versa. This produces incorrect import ordering rules.\n\n**Fix:** Maintain an explicit stdlib module list. Check against it before classifying an import. When uncertain, check the module's origin via `sys.stdlib_module_names` (Python 3.10+) rather than guessing.\n\n---\n\n### Branch inflation from remote tracking refs\n\n**What happens:** `git branch -a` returns both local branches and remote trackin"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1961,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:40:09.389Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:49:24.604Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}