Skip to content
Skills Library
Programming · Writing

guide

/guide

Read and maintain this repo's guide/ folder, the reviewed description of the codebase as it is today (architecture, principles, known issues). Use it before or during a code change to find the architecture and principles that apply, when a code change is done to update the guide in the same PR, after a merge or rebase to realign the guide with the code, when a principle may need to change, or to create a guide in a repo that has none.

Repository
find_home ↗
Licence
Apache-2.0
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/check_links.py

What it does and when to use it

Read and maintain this repo's guide/ folder, the reviewed description of the codebase as it is today (architecture, principles, known issues). Use it before or during a code change to find the architecture and principles that apply, when a code change is done to update the guide in the same PR, after a merge or rebase to realign the guide with the code, when a principle may need to change, or to create a guide in a repo that has none.

Original author description

Read and maintain this repo's guide/ folder, the reviewed description of the codebase as it is today (architecture, principles, known issues). Use it before or during a code change to find the architecture and principles that apply, when a code change is done to update the guide in the same PR, after a merge or rebase to realign the guide with the code, when a principle may need to change, or to create a guide in a repo that has none.

How it works

  1. Rules
  2. Layout
  3. Reading: before or during a task
  4. Updating: when a code change is done
  5. Logging an issue: any time
  6. After a merge or rebase
  7. Changing a principle
  8. Starting a guide in a new repo
  9. Writing style
Original SKILL.md headings · 101 lines, 1,420 words
SKILL.md preview
---
name: guide
description: Read and maintain this repo's guide/ folder, the reviewed description of the codebase as it is today (architecture, principles, known issues). Use it before or during a code change to find the architecture and principles that apply, when a code change is done to update the guide in the same PR, after a merge or rebase to realign the guide with the code, when a principle may need to change, or to create a guide in a repo that has none.
---

# Guide

The guide is the `guide/` folder at the root of the repository being changed. In a workspace with several repos, it is the `guide/` of the repo you are working in. It describes that repository **as it is today**: what it does, how it is built, the principles every change follows, and the known issues to keep in mind. It is written for people and for coding agents.

The guide is an add-on to however you already work. Plan, design, debug or run QA sessions your own way, with any agent. Use the guide as a reference whenever it helps, and leave it true when your change is done. It is not an archive and not a process.

## Rules

1. **Current state only.** No change logs, task notes, QA transcripts, dates or "now/recently". History lives in git and in PR descriptions.
2. **Same PR.** The guide changes in the same PR as the code it describes.
3. **Who wins when code and guide disagree.**
   - `principles/`: the code is wrong. Fix the code, or propose a principle change (see below).
   - `overview.md`, `architecture/`: the guide is out of date. Fix the guide.
   - `issues/`: check the code; update or remove the entry.
4. **Principles are a team agreement.** Never edit `principles/` on your own initiative or as a side effect. A change is proposed to the user and reviewed with the teammates who work on the repo.
5. **Load little.** Read the overview, then only the pages that cover the task.

## Layout

```
guide/
  overview.md      entry point: what the app is, directory map, page index, what to read before which change
  architecture/    how it is built today: components, flows, where the code lives
  principles/      the line we hold: what to do, what to optimise, what to avoid; each rule with Why and Enforced by
  issues/          known limits that affect how code must be written (tracking stays in the issue tracker)
```

Each part branches into subfolders as the repo grows (`principles/prompting/`, `principles/telemetry.md`, `architecture/flows/`). Templates for every page type: [references/skeleton.md](references/skeleton.md).

## Reading: before or during a task

1. Read `guide/overview.md`.
2. From its index and directory map, pick the pages that cover the files or area you will touch. Read those in full. Do not load the rest.
3. Read every principle that applies to those files. If the task would break one, say so **before** writing code: name the principle, then offer a way that respects it, or a principle change for team review.
4. When debugging or touching a known weak spot, read the matching `issues/` entries.

If there is no `guide/` folder, say so and offer to create one (see Starting a guide).

## Updating: when a code change is done

Do this pass when the code change is complete: before committing or opening the PR, or when the user says they are done. If the user is about to finish without it, remind them once.

1. List what changed: `git diff --name-only <base>...HEAD` plus `git status --short` for uncommitted work. `<base>` is the target branch (ask if unclear; default `main`).
2. For each changed file, find guide pages that mention it, its folder or its main names: `grep -rln "<path, module or class>" guide/`. Also check pages whose topic covers the change even without a direct link.
3. Rewrite what the change made untrue: text, diagrams, directory map, links, names. Describe the result ("X does Y"), never the change ("X now does Y since #123"). A link with a line anchor (`#L42`) into a changed file: check that the line still shows the named symbol, and move the anchor if it does not. A flow the change altered: redraw its diagram.
4. A new component, flow, agent or integration: extend the matching architecture page (or add one) and the overview index.
5. Issues: a known issue fixed by the change, delete its entry (the PR records the fix). Something left imperfect on purpose, a pending fix, or a new known limit: add a short entry (see Logging an issue), so it is not forgotten.
6. A principle affected: stop and follow **Changing a principle**.
7. Run the checks locally:
   - `python3 <this skill's folder>/scripts/check_links.py --guide-dir <repo>/guide` (the skill's folder is where this file is, e.g. `.github/skills/guide/` or `.claude/skills/guide/`)
   - the tests named under "Enforced by" in the principles that cover the changed files.
8. Report in a few lines: pages updated, and anything left for the user to decide.

If the change touches nothing the guide describes, say "guide checked, no update needed" and stop.

## Logging an issue: any time

When the user finds a problem that is not part of the current task ("log this in the guide"), or the Updating pass finds pending work:

1. Add an entry to `guide/issues/` under the matching area, in the issue format ([references/skeleton.md](references/skeleton.md)): title, impact, what goes wrong and when, fix direction. Point to the code with relative links.
2. If the entry is important (impact high or medium, or the user says so), ask: "Open a GitHub issue for this too?" Ask once per batch, listing the candidates. Never create one without a yes.
3. On a yes, create it with the GitHub tool available (`gh issue create --title … --body …` or the GitHub connector), with the entry text as the body, and add the issue link to the entry's title line.
4. Never put plans, progress or to-do lists in `issues/`: one entry per open problem, deleted when fixed.

## After a merge or rebase

Guide files conflict like code, and can also go silently out of date when the other branch changed what they describe.

1. Resolve code conflicts first.
2. For each conflict in `guide/`, read both versions and the merged code, and write the text that is true **now**. Keep both sides' additions when both still hold.
3. Then run the Updating pass against the new base, so pages your branch edited also reflect what the other branch changed. To list what the other side changed: `git diff --name-only $(git merge-base HEAD <base>) <base>`.
4. Run the link check.

## Changing a principle

Principles set the direction for everyone working on the repo, so they change only by agreement.

1. Tell the user which principle no longer fits and why, and propose the new wording in the principle format (Rule, Why, Bad, Good, Enforced by).
2. Edit the principle only after the user agrees, in the same PR as the code, together with its test.
3. Ask the user to call it out at the top of the PR description ("Principle change: <name>: <one line>") and to request review from the teammates or code owners of the repo. Never let a principle change ride along unannounced.

## Starting a guide in a new repo

Follow [references/bootstrap.md](references/bootstrap.md). In short: create the skeleton, write the overview and architecture from the code, and only **propose** principles and issues for the user to confirm. Never invent a principle.

## Writing style

- Short, plain sentences. One definition per concept.
- Link code with relative paths from the page (`../../src/core/config.py`), so the link check can verify them.
- **Explain flows with diagrams.** Every flow, interaction or decision a page describes gets a mermaid diagram:
  - `sequenceDiagram` for who calls whom and in what order (requests, callbacks, concurrent runs, an external service);
  - `flowchart` for decisions, branches, pipelines and data flow;
  - `stateDiagram-v2` for a lifecycle; a table for a comparison.

  One idea per diagram, about 15 nodes at most, arrows labelled with the call or the data. Diagrams are drawn from the code as it is, like the text.
- **Make code references clickable, down to the line.** Link the symbol the text is about, with its line: ``[`build()`](../../src/core/builder.py#L90)``, or a range `#L90-L104`. The link text names the symbol, so a reader can still find it after the lines move. Take the line from the file (`grep -n`), never from memory. The link check fails when an anchor points past the end of the file; the Updating pass keeps anchors on the right line.
- Keep links out of the diagram (renderers differ in how they handle clicks in mermaid): under a diagram, a short table maps each step to its code link.
- No dates or narratives. The only history allowed is a commit hash in a principle's Bad example.
- Split a page into a subfolder when it passes about 400 lines or covers two topics, and update the overview index.
Files in this package (4)
  • SKILL.md 9 KB
  • references/bootstrap.md 2 KB
  • references/skeleton.md 3 KB
  • scripts/check_links.py 3 KB

Versions

RepositoryScoreLicence
This page · MassimilianoBiancucci/find_home100Apache-2.0
YuDefine/nuxt-supabase-starter100MIT
toss/es-toolkit100MIT
vecten/vecten-open100Apache-2.0
testany-io/testany-agent-skills100MIT
rlibre/x4100MIT
CoeusInstitute/hermes-ide100MIT
voyager67/Claude-Garage100MIT
HeyRenan/showreel100MIT

Database snapshot: 13.11.2026 · package version f042c4544d8e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90archwhere
    Maintain a declared architecture map and place every code change on it. Use when starting work in a repo with arch/architecture.json, when asked "what part of the system is this?", or to scaffold the map in a repo that lacks one.
  • 100dev-docs
    Use when writing, organizing or updating project documentation - creating a docs/ folder, adding a doc page, recording a decision (ADR), writing a mission, architecture or reference page, or keeping docs in step with a code change. Sets the folder structure, the writing style,…
  • 90principles
    Use this skill for engineering principles across core design, architecture, verification, delegation, and meta structure. Read the reference file of each principle that applies.
  • 100apply-architecture
    Use when a change adds, moves or splits a module, or changes a public interface. Checks the design against the architecture principles in this repository.
  • 100principle-ship
    Apply when finishing a code change, or when asked to ship, merge, deploy or call a task done. Done means a PR opened, the diff self-reviewed, CI green, merged, and the deploy confirmed live.
  • 100backend-architecture-principles
    Language-agnostic backend architecture and code-quality rules. Use when designing services, structuring a backend codebase, writing business logic, handling errors, configuration, logging, background jobs, or reviewing backend code for maintainability.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.