New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Update Spec

by jlifeng in jlifeng/JobPilot

Update Code-Spec - Capture Executable Contracts. An agent skill from jlifeng/JobPilot.

Apache-2.0Auto-check passedDevelopment

Install Update Spec

skills CLI
$ npx skills add jlifeng/JobPilot --skill update-spec -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jlifeng/JobPilot update-spec --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jlifeng/JobPilot.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/update-spec .claude/skills/update-spec && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
update-spec
GitHub stars
140
Token cost
~2.4k tokens
SKILL.md length
859 words
Files
1
Skills in repo
5
Repo updated
First seen
Licence
Apache-2.0

At a glance

Update Code-Spec - Capture Executable Contracts. An agent skill from jlifeng/JobPilot.

  • Works in 5 steps: Identify What You Learned → Classify the Update Type → Read the Target Code-Spec → …
  • Tasks that involve Architecture decision records
  • SKILL.md covers Code-Spec First Rule (CRITICAL), When to Update Code-Specs, Spec Structure Overview and Update Process, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Update Spec is an agent skill from jlifeng/JobPilot. Update Code-Spec - Capture Executable Contracts

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Architecture decision records. The repository describes itself as: JobPilot — Zero-Deployment AI Resume Builder, JD Matcher & Mock Interview Assistant JobPilot — 开箱即用的桌面端 AI 求职助手，支持简历优化、岗位匹配与模拟面试. The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Architecture decision records

Example prompts

  • “/update-spec”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Identify What You Learned
  2. Classify the Update Type
  3. Read the Target Code-Spec
  4. Make the Update
  5. Update the Index (if needed)

What it can do on your machine

Read from SKILL.md and the folder at commit 7f33542. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Update Spec loads about 2.4k tokens when it runs. Until then it costs about 15 tokens; SKILL.md has 859 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~15
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jlifeng/JobPilot at commit 7f33542, republished under its Apache-2.0 licence (© jlifeng). 859 words, ~2,356 tokens.

Download SKILL.mdSave it as .claude/skills/update-spec/SKILL.md (or your agent's skills folder).
name
update-spec
description
Update Code-Spec - Capture Executable Contracts

Update Code-Spec - Capture Executable Contracts

When you learn something valuable (from debugging, implementing, or discussion), use this skill to update the relevant code-spec documents.

Timing: After completing a task, fixing a bug, or discovering a new pattern

Code-Spec First Rule (CRITICAL)

In this project, "spec" for implementation work means code-spec:

  • Executable contracts (not principle-only text)
  • Concrete signatures, payload fields, env keys, and boundary behavior
  • Testable validation/error behavior

If the change touches infra or cross-layer contracts, code-spec depth is mandatory.

Required sections for infra/cross-layer specs:

  1. Scope / Trigger
  2. Signatures (command/API/DB)
  3. Contracts (request/response/env)
  4. Validation & Error Matrix
  5. Good/Base/Bad Cases
  6. Tests Required (with assertion points)
  7. Wrong vs Correct (at least one pair)

When to Update Code-Specs

TriggerExampleTarget Spec
Implemented a featureAdded template download with gigetRelevant backend/ or frontend/ file
Made a design decisionUsed type field + mapping table for extensibilityRelevant code-spec + "Design Decisions" section
Fixed a bugFound a subtle issue with error handlingbackend/error-handling.md
Discovered a patternFound a better way to structure codeRelevant backend/ or frontend/ file
Hit a gotchaLearned that X must be done before YRelevant code-spec + "Common Mistakes" section
Established a conventionTeam agreed on naming patternquality-guidelines.md
New thinking trigger"Don't forget to check X before doing Y"guides/*.md (as a checklist item, not detailed rules)

Key Insight: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.

Spec Structure Overview

.trellis/spec/
├── backend/           # Backend coding standards
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
├── frontend/          # Frontend coding standards
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
└── guides/            # Thinking checklists (NOT coding specs!)
    ├── index.md       # Guide index
    └── *.md           # Topic-specific guides
CRITICAL: Code-Spec vs Guide - Know the Difference
TypeLocationPurposeContent Style
Code-Specbackend/*.md, frontend/*.mdTell AI "how to implement safely"Signatures, contracts, matrices, cases, test points
Guideguides/*.mdHelp AI "what to think about"Checklists, questions, pointers to specs

Decision Rule: Ask yourself:

  • "This is how to write the code" → Put in backend/ or frontend/
  • "This is what to consider before writing" → Put in guides/

Example:

LearningWrong LocationCorrect Location
"Use reconfigure() not TextIOWrapper for Windows stdout"❌ guides/cross-platform-thinking-guide.md✅ backend/script-conventions.md
"Remember to check encoding when writing cross-platform code"❌ backend/script-conventions.md✅ guides/cross-platform-thinking-guide.md

Guides should be short checklists that point to specs, not duplicate the detailed rules.

Update Process

Step 1: Identify What You Learned

Answer these questions:

  1. What did you learn? (Be specific)
  2. Why is it important? (What problem does it prevent?)
  3. Where does it belong? (Which spec file?)
Step 2: Classify the Update Type
TypeDescriptionAction
Design DecisionWhy we chose approach X over YAdd to "Design Decisions" section
Project ConventionHow we do X in this projectAdd to relevant section with examples
New PatternA reusable approach discoveredAdd to "Patterns" section
Forbidden PatternSomething that causes problemsAdd to "Anti-patterns" or "Don't" section
Common MistakeEasy-to-make errorAdd to "Common Mistakes" section
ConventionAgreed-upon standardAdd to relevant section
GotchaNon-obvious behaviorAdd warning callout
Step 3: Read the Target Code-Spec

Before editing, read the current code-spec to:

  • Understand existing structure
  • Avoid duplicating content
  • Find the right section for your update
bash
cat .trellis/spec/<category>/<file>.md
Show full SKILL.md (362 more words)Show less
Step 4: Make the Update

Follow these principles:

  1. Be Specific: Include concrete examples, not just abstract rules
  2. Explain Why: State the problem this prevents
  3. Show Contracts: Add signatures, payload fields, and error behavior
  4. Show Code: Add code snippets for key patterns
  5. Keep it Short: One concept per section
Step 5: Update the Index (if needed)

If you added a new section or the code-spec status changed, update the category's index.md.

Update Templates

Mandatory Template for Infra/Cross-Layer Work
markdown
## Scenario: <name>

### 1. Scope / Trigger
- Trigger: <why this requires code-spec depth>

### 2. Signatures
### 3. Contracts
### 4. Validation & Error Matrix
### 5. Good/Base/Bad Cases
### 6. Tests Required
### 7. Wrong vs Correct
#### Wrong
...
#### Correct
...
Adding a Design Decision
markdown
### Design Decision: [Decision Name]

**Context**: What problem were we solving?

**Options Considered**:
1. Option A - brief description
2. Option B - brief description

**Decision**: We chose Option X because...

**Example**:
\`\`\`typescript
// How it's implemented
code example
\`\`\`

**Extensibility**: How to extend this in the future...
Adding a Project Convention
markdown
### Convention: [Convention Name]

**What**: Brief description of the convention.

**Why**: Why we do it this way in this project.

**Example**:
\`\`\`typescript
// How to follow this convention
code example
\`\`\`

**Related**: Links to related conventions or specs.
Adding a New Pattern
markdown
### Pattern Name

**Problem**: What problem does this solve?

**Solution**: Brief description of the approach.

**Example**:
\`\`\`
// Good
code example

// Bad
code example
\`\`\`

**Why**: Explanation of why this works better.
Adding a Forbidden Pattern
markdown
### Don't: Pattern Name

**Problem**:
\`\`\`
// Don't do this
bad code example
\`\`\`

**Why it's bad**: Explanation of the issue.

**Instead**:
\`\`\`
// Do this instead
good code example
\`\`\`
Adding a Common Mistake
markdown
### Common Mistake: Description

**Symptom**: What goes wrong

**Cause**: Why this happens

**Fix**: How to correct it

**Prevention**: How to avoid it in the future
Adding a Gotcha
markdown
> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.

Interactive Mode

If you're unsure what to update, answer these prompts:

  1. What did you just finish?

    • Fixed a bug
    • Implemented a feature
    • Refactored code
    • Had a discussion about approach

  2. What did you learn or decide?

    • Design decision (why X over Y)
    • Project convention (how we do X)
    • Non-obvious behavior (gotcha)
    • Better approach (pattern)

  3. Would future AI/developers need to know this?

    • To understand how the code works → Yes, update spec
    • To maintain or extend the feature → Yes, update spec
    • To avoid repeating mistakes → Yes, update spec
    • Purely one-off implementation detail → Maybe skip

  4. Which area does it relate to?

    • Backend code
    • Frontend code
    • Cross-layer data flow
    • Code organization/reuse
    • Quality/testing

Quality Checklist

Before finishing your code-spec update:

  • Is the content specific and actionable?
  • Did you include a code example?
  • Did you explain WHY, not just WHAT?
  • Did you include executable signatures/contracts?
  • Did you include validation and error matrix?
  • Did you include Good/Base/Bad cases?
  • Did you include required tests with assertion points?
  • Is it in the right code-spec file?
  • Does it duplicate existing content?
  • Would a new team member understand it?

Relationship to Other Commands

Development Flow:
  Learn something → $update-spec → Knowledge captured
       ↑                                  ↓
  $break-loop ←──────────────────── Future sessions benefit
  (deep bug analysis)
  • $break-loop - Analyzes bugs deeply, often reveals spec updates needed
  • $update-spec - Actually makes the updates (this skill)
  • $finish-work - Reminds you to check if specs need updates

Core Philosophy

Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.

The goal is institutional memory:

  • What one person learns, everyone benefits from
  • What AI learns in one session, persists to future sessions
  • Mistakes become documented guardrails

© jlifeng, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/update-spec of jlifeng/JobPilot.

Open the folder on GitHubat commit 7f33542

Compare with similar skills

Update Spec next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Update Spec compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Update Spec this skilljlifeng/JobPilot140—~2.4kAutomated safety check: PassApache-2.0
PR Design DocOpenHands/OpenHands90k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3814 repos~2.4kAutomated safety check: PassMIT
Architecture DecisionDonchitos/Claude-Code-Game-Studios26k—~1.7kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Domain Modelingbrim-borium/spotify_sdk1665 repos~806Automated safety check: PassApache-2.0

Similar skills

  • PR Design Doc

    OpenHands/OpenHands

    For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…

    90k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed

  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    381 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed

  • Architecture Decision

    Donchitos/Claude-Code-Game-Studios

    Create an ADR documenting a technical decision: context, alternatives considered, consequences.

    26k GitHub stars~1.7k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed

  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 5 repos~806 tokens
    DevelopmentAuto-check passed

  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    176 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed

More from jlifeng/JobPilot

  • Brainstorm

    jlifeng/JobPilot

    Brainstorm - Requirements Discovery (AI Coding Enhanced). An agent skill from jlifeng/JobPilot.

    140 GitHub stars~3.1k tokensUpdated today
    Auto-check passed

  • Break Loop

    jlifeng/JobPilot

    Break the Loop - Deep Bug Analysis

    140 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Finish Work

    jlifeng/JobPilot

    Finish Work - Pre-Commit Checklist

    140 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Start

    jlifeng/JobPilot

    Start Session

    140 GitHub stars~2.4k tokensUpdated today
    Auto-check passed

Categories

Questions about Update Spec

What does Update Spec do?

Update Code-Spec - Capture Executable Contracts. An agent skill from jlifeng/JobPilot. Update Spec is an agent skill from jlifeng/JobPilot.

When should I use Update Spec?

Update Spec fits situations like: tasks that involve Architecture decision records.

How do I install Update Spec in Claude Code?

Run `npx skills add jlifeng/JobPilot --skill update-spec -a claude-code`. Or copy the skill folder (.agents/skills/update-spec in jlifeng/JobPilot) into .claude/skills/update-spec in your project. Claude Code loads it when a task matches its description.

How do I install Update Spec in Codex?

Run `npx skills add jlifeng/JobPilot --skill update-spec -a codex`. Or copy the skill folder (.agents/skills/update-spec in jlifeng/JobPilot) into .agents/skills/update-spec in your project. Codex loads it when a task matches its description.

Can I use Update Spec in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jlifeng/JobPilot --skill update-spec -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/update-spec, .gemini/skills/update-spec, .github/skills/update-spec and .opencode/skills/update-spec in your project.

What does Update Spec need to run?

SKILL.md names no scripts, command-line tools or credentials: Update Spec is instructions for the agent only.

Does Update Spec access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Update Spec safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Update Spec use?

Update Spec is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Update Spec use?

About 2.4k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Update Spec?

Skills that share tags, products or a category with Update Spec: PR Design Doc (OpenHands/OpenHands, 90k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 381 stars), Architecture Decision (Donchitos/Claude-Code-Game-Studios, 26k stars) and Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Update Spec?

jlifeng (a GitHub user) maintains it in jlifeng/JobPilot, which has 140 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on October 8, 2026.

Source: jlifeng/JobPilot on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.