Files
skillshare/AGENTS.md
T
Willie 262e639701 docs: add task-routed agent wiki
Add a shared instruction kernel and byte-budgeted topic router so agents load only task-relevant repository guidance. Wire drift checks into local and CI workflows and point project skills at the routed topics.
2026-09-25 02:32:37 +08:00

5.1 KiB

AGENTS.md — skillshare

skillshare is a Go CLI with a React dashboard and a Docusaurus documentation site. It synchronizes skills, agents, extras, MCP servers, and plugins across AI coding tools. This file contains only rules needed for every task; load task-specific details through the context topics below.

Language

  • Instruction files, internal documentation, public English documentation, code, identifiers, comments, and commit messages use English.
  • Reply to users in their language; default to Traditional Chinese when the user writes Chinese.
  • README.md is the public English source. Keep translated READMEs aligned with its existing localization conventions. Preserve history files in their original language.

Always Applies

  • Use executable evidence. Verify facts that affect conclusions or implementation against current source, configuration, installed versions, or actual command output. Distinguish facts, assumptions, and uncertainty.
  • Preserve user changes and keep scope minimal. Inspect the working tree before editing, then trace relevant definitions, callers, tests, and existing patterns. Never overwrite unrelated changes or perform opportunistic cleanup.
  • Keep the docs true. When documentation disagrees with code, verify the code and fix the stale documentation in the same task. Update a topic whenever a change alters behavior it describes. Put completed milestone logs in wiki/history/ and add them to the index. Run python3 scripts/ai-context.py check after documentation changes. The maintenance procedure is in the ai-context topic.
  • Run commands in the correct environment. Execute the skillshare CLI, Go builds/tests, UI tooling, and website tooling inside the devcontainer. The host is only for file edits, read-only searches, Git inspection, and the context-router check. Load testing before execution or debugging.
  • Verify in proportion to risk. Start with the narrowest check that proves the change. Reproduce bugs and add regression tests when practical. Never skip, disable, or weaken validation to obtain a passing result.
  • Respect authorization boundaries. Reviews, investigations, and diagnoses are read-only by default. Do not commit, push, publish, deploy, install global tools, or perform destructive or irreversible actions unless explicitly authorized.
  • Use Git safely. Never overwrite user changes. When asked to commit, stage only task-owned files and follow repository conventions; otherwise use an English Conventional Commit with a body explaining why.
  • Keep helper files in the repository. Put reusable helper scripts in scripts/<area>/ and test runbooks in ai_docs/tests/. Do not store persistent task artifacts outside the repository.
  • Report outcomes precisely. State what changed, why, actual verification results, limitations, and preserved unrelated changes. Explicitly identify checks that were not run.

Hard Limits

  • Never run ss, skillshare, go test, make test, or frontend package scripts on the host.
  • Never expose, hardcode, or commit secrets, tokens, credentials, or private user-path contents.
  • Never bypass audits, hooks, tests, trust prompts, or native client confirmation.
  • Never change permissions, delete persistent data, rewrite Git history, commit, tag, push, or release without explicit authorization.
  • Resolve and confirm the exact target before a destructive action. Never recursively delete a workspace root, home directory, or unresolved broad path.

Load Context Per Task

python3 scripts/ai-context.py list      # list topics and selection guidance
python3 scripts/ai-context.py <topic>   # print only that topic's sources
python3 scripts/ai-context.py check     # validate paths, headings, orphans, and byte budgets
Topic Use when
architecture Tracing repository structure, data flow, or CLI/Web API boundaries
cli-development Adding or changing Go CLI commands, flags, handlers, TUIs, or mutating behavior
testing Building, testing, reproducing bugs, using the devcontainer/ssenv, or running E2E runbooks
frontend Changing React, CSS, layout, or visual behavior in ui/ or website/
documentation Updating README files, website docs, command flags, translations, or the built-in skill
release Writing changelogs or release notes, bumping versions, tagging, or releasing
audit Read-only consistency checks for flags, docs, tests, targets, handler splits, oplog, or Web API
ai-context Adding, moving, or splitting wiki topics, or fixing router checks

Pick the single closest topic by default. Load a second only when a task genuinely crosses two seams. If no topic fits, read wiki/README.md.

To add a topic:

  1. Put its content in wiki/.
  2. Map it in docs/ai-context.json.
  3. Add it to this table and wiki/README.md.
  4. Run check.

Split an over-budget topic instead of raising its cap. Skills are workflow adapters that load topics; they are not the sole source of repository rules.

Verification

python3 scripts/ai-context.py check

# Code changes: run inside the devcontainer after loading `testing`
make check