agentleFS
TsukiNi22TsukiNi22/skills/skills/python/python-comments/SKILL.md

python-comments

Skill1 starsChanged 3 days agoMITView on GitHub

How Tsukini writes comments in Python - the Python equivalent of cpp-comments, from his scripts (libutils cmake/scripts, MAGIC) - the Xartania header (63 double quotes), the ##### Section ##### banners, the "# Import that can't be in the try" / "# Import that can be checked" labels, the "# Used for ..." trailing comment of every import, trailing comments on constants (meaning, unit, values, aligned in a group), block comments above the code, short indented docstrings for classes and public methods, no Sphinx / Google docstrings, notations and tone. Use whenever adding, rewriting or reviewing comments or docstrings in Python code for the user, or when generating Python code that needs comments.

  • Pipes a download into a shell

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Always in English, short, no final period.

    line 12
  2. Very specific:

    Import labels (exact): # Import that can't be in the try, # Import that can be checked.

    line 21
  3. Very specific:

    When xstyle is installed (command -v xstyle), check what was written or reviewed with it instead of re-reading the rules by hand: xstyle …

    line 78

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Tsukini comment style (Python)

<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).

Always in English, short, no final period. Comment the why and the non-obvious, never paraphrase the code. General rules of every language: comments (section 1). Code style: python-style. When a file already has its own comment style (an older file of MAGIC with """ Import """ banners), the local style wins.

1. Structure comments (exact strings)

  • File header: python3 <cpp-class>/scripts/header.py --file <name>.py --desc "..." (63 ", banner, Edition: / File Name: / File Description: with ## lines), never written by hand.
  • Section banners, at column 0, one empty line before: ##### Import #####, ##### Const #####, ##### Tools #####, ##### Class #####, ##### Program #####, ##### Declaration #####, ##### Tests ##### (only the used ones).
  • Import labels (exact): # Import that can't be in the try, # Import that can be checked; the optional install block # Try to install dependencies (failsafe); the guard comments # Check if the program is call and not imported / # Check if the program is imported and not call (the user's wording, kept as is).

2. Trailing comments (the most used)

    from pathlib import Path # Used to create & edit files and to get the file name
    exit(255) # Special exit code (only place used)
data = {} # {code: [message, info, restriction], ...}
    FATAL: int  = 0b1000    # Global error, the whole execution stops          (100% execution stop)
    LOCAL: int  = 0b100     # Local error, the local execution probably stops  (some chance of execution stop)
    SIZE_MAX: int = 2**64 - 1  # size_t max on 64 bits machine
  • Every checked import: # Used for <what> / # Used to <do what>.
  • Constants: meaning, unit, values (0 = unlimited), the shape of a container ({code: [message, info], ...}, <id, name> for a tuple), alternatives with | (# dark | light), precisions in (...); aligned in a group of constants (fields and comments in columns).
  • Private / free functions and the def of a script: the behavior in a trailing comment of the def line (def _parse(self, line: str) -> int: # one device value).
  • Danger in upper case: # DOES NOT CLOSE THE PORT!!!, (only!).

3. Block comments above the code

    # Init the loading overlay
    loading = LoadingOverlay(window, ...)

    # Wait until at least one device have been found or timeout
    while time() - start <= timeout and not card.values:

One line, upper case first letter, no final period, describes the intent of the block, an empty line before the block. word: precision form for a nuance (# Not an error: the port can be closed by the user). Small labels in lower case are fine for the parts of a block (# code, # message, # info in a loop building several strings).

4. Docstrings (rare, short)

class Parameters:
    """
        Class to handle the parameters edition / reading
    """

    def get_parameter(self, name: str) -> str | None:
        """
            Get the value of a parameter
        """
  • Classes and public methods only: one or two lines, the text indented by 4 more than the quotes (8 spaces inside a class), the quotes alone on their lines. Frozen dataclasses of const.py too ("""\n Return values\n """).
  • Never Sphinx / Google / NumPy fields (:param x:, Args:, Returns:): the types are in the signature, the meaning of a parameter goes in its name or a trailing comment. MAGIC's older :param docstrings are not reproduced.
  • Scripts: no module docstring (the header is the description), no docstring on the functions.

5. Misc

  • Disabled code kept only when it is a real alternative, with # and no space (#&& dnf remove -y gnupg2).
  • No TODO / FIXME (G-TODO of xstyle): describe the limitation in a normal comment.
  • pass # Nothing is never written: pass alone is the empty body.

Checking (xstyle)

When xstyle is installed (command -v xstyle), check what was written or reviewed with it instead of re-reading the rules by hand: xstyle --rtk <files|dirs> [-r] (always --rtk: compact output made for the assistant), xstyle --rtk --fix [CODES] <paths> for the fixable ones (-n to preview), -c PY,G-TODO for the rules of this skill, xstyle -x CODE to explain one. Not installed: apply the rules by hand and say once that curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s then sudo dnf|apt|pacman install xstyle (packages of my-universe, sources: TsukiNi22/xstyle; no curl: wget -qO- instead of curl -fsSL) would check them. Its findings are heuristic: the local style of a file wins.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.