holocron/plugins/gitea/.apm/skills/gitea-files/SKILL.md

name, description, compatibility, metadata, allowed-tools

name	description	compatibility	metadata	allowed-tools
gitea-files	Use when reading or writing individual files or directory trees in a Gitea repository via the Gitea MCP server: reading a file's contents, listing a directory, walking a full repository tree, creating a new file, updating an existing file, or deleting a file. Triggers on "read this file from the repo", "what's in this directory", "show me the repo tree", "create/update a file in Gitea", "commit this file to the branch", "delete this file from the repo" — even when the user doesn't say "Gitea" explicitly, as long as the target is a Gitea-hosted repository. Do not use for local filesystem file operations (use Read/Write/Edit), for branch or commit history (use gitea-branches), or for opening a pull request around a file change (use gitea-prs after the file write completes here).	Requires the Gitea MCP server configured with a token scoped to at least write:repository. Tested with a token holding write:issue + write:repository; write:issue is not actually required for any of this domain's five tools.	category source_keys gitea gitea-mcp-repo gitea-mcp-slim-go context7-websites-gitea	mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__gitea__get_repository_tree mcp__gitea__create_or_update_file mcp__gitea__delete_file

Gotchas

• A 404 from any read call may actually be a 403 in disguise. get_file_contents, get_dir_contents, and get_repository_tree all gate on write:repository scope, not just read access — some Gitea endpoints return 404 instead of 403 when the token's scope is insufficient, to avoid leaking whether the resource exists. If a read fails with 404 on a path you're confident is correct, check the token's configured scopes before concluding the file or directory doesn't exist.
• SHA is the concurrency token for every write — and it lives at the top level of get_file_contents's response, not nested under content. create_or_update_file without sha is always treated as a create: if the path already exists, Gitea returns HTTP 409. delete_file has no optional path at all — omitting sha returns HTTP 422. The safe sequence for any update or delete is always: call get_file_contents first, read the top-level sha field, then pass that exact value to the write call. Never guess or reuse a stale SHA — a mismatched SHA is rejected the same as a missing one.
• A write can also fail because the branch requires signed commits — a separate failure mode from a bad SHA. create_or_update_file and delete_file create commits server-side via a bare API token call with no 2FA/PGP context. If the target branch's protection rule requires signed commits, Gitea rejects the write outright — surfaced as a generic 403 or 422, not an error naming "signed commit required," and reads against that same branch keep succeeding right up until you try to write. When a write fails without a clean 409 (missing/stale SHA) or 404 (bad path) explanation, check whether the branch's protection rule requires signed commits before assuming the SHA is wrong and retrying.
• A large create_or_update_file payload can hit a reverse-proxy 413 that has nothing to do with Gitea. content is base64-encoded, which inflates the payload ~33% over the raw file size; a 413 is commonly a reverse-proxy body-size limit in front of the Gitea instance, not a Gitea-side rejection. No amount of retrying, or changing the SHA, path, or branch, will fix it — it needs the proxy's config raised, which is outside this skill's or the calling agent's control. Surface that distinction to the user instead of retrying the same call.
• get_dir_contents and get_repository_tree are not SHA sources for a specific file's write. get_dir_contents entries carry no sha at all. get_repository_tree entries do carry a sha (a blob/tree hash), but fetching it means an extra round trip with no content — get_file_contents is the canonical path since it returns the decoded content and the write-ready sha in one call.
• owner and repo are always caller-supplied inputs, never resolved here. This skill doesn't infer them from a git remote. If invoked directly by a human, ask for them if not stated. If invoked by gitea-workflow or an orchestrating agent, expect them to already be resolved and passed in.
• Direct commits to a branch are a first-class action, not a workaround. Gitea's own web UI defaults to editing files directly against a branch — create_or_update_file/delete_file used that way is normal, not an API escape hatch to avoid. The SHA-currency requirement above is the actual risk to manage, not the act of committing directly.
• ref (reads) vs. branch_name (writes) are different parameters for the same concept. get_file_contents, get_dir_contents, and get_repository_tree (as tree_sha) all accept a branch name, tag, or commit SHA to select what to read. create_or_update_file and delete_file instead take branch_name — the branch the commit lands on. Don't conflate the two when chaining a read into a write.
• Content is base64. create_or_update_file's content parameter is base64-encoded file content, not raw text — encode before calling. get_file_contents's response content is likewise base64-encoded (decode after reading), unless withLines: true is passed for a numbered-line view.

Reading

• Single file: get_file_contents(owner, repo, ref, path). Pass withLines: true only when you need line numbers for referencing specific lines (e.g. quoting a snippet back to the user); omit it for a normal content fetch.
• One directory level: get_dir_contents(owner, repo, ref, path) — returns immediate entries only (name, path, type, size), no recursion, no SHA, no content.
• Whole tree: get_repository_tree(owner, repo, tree_sha, recursive) — tree_sha accepts a SHA, branch, or tag name despite the name. Set recursive: true to walk subdirectories in one call. Response includes truncated: true when a page doesn't hold every entry — page through with page/per_page (default page: 1, per_page: 30) until you get fewer results than per_page.

Writing

• Creating a new file: call create_or_update_file(owner, repo, path, content, message, branch_name) with sha omitted entirely.
• Updating an existing file: call get_file_contents(owner, repo, ref: branch_name, path) first, take the top-level sha, then call create_or_update_file(..., sha: <that value>).
• Deleting a file: call get_file_contents first the same way, then delete_file(owner, repo, path, message, branch_name, sha: <that value>) — sha is required, no create-style fallback exists.
• Creating a new branch as part of the write: pass new_branch_name on create_or_update_file to branch off before the commit lands, instead of calling a separate branch-creation step.

If the change needs review before merging, or targets a protected branch, hand off to gitea-prs after the write lands here to open the pull request — this skill's scope ends at the commit.

If you need the full multi-call sequence rather than the single-call summary above — e.g. branching off as part of a file push ahead of opening a PR, or recovering a SHA you didn't capture earlier — read references/examples.md.